crab push
Push committed pointer blobs, backing objects, and Git refs. crab push uses
the same repository outcome as git push through git-remote-crab, while its
native pipeline can upload independent objects concurrently.
When REMOTE is omitted, Crab prefers the current branch's Crab-compatible
upstream, then a remote named crab, then the only other Crab-compatible
remote. If several Crab remotes remain, pass the remote name explicitly.
Synopsis
crab push [OPTIONS] [REMOTE] [REFSPECS]...Arguments
| Argument | Required | Description |
|---|---|---|
REMOTE | No | Remote name or URL; auto-detects a Crab-compatible remote before falling back to the upstream remote or origin |
REFSPECS | No | Refspecs to push; defaults to the current branch |
Managed push
When the remote is crab://crab.build/acme/models or another configured
managed authority, Crab:
- Resolves the logical repository and current authorization.
- Submits estimated bytes and objects for service-owned quota and concurrency admission.
- Prepares a durable push session and exact staging scope.
- Flushes and verifies every required staged xorb and bundle object.
- Asks the service to recompute policy-relevant paths and validate Git connectivity.
- Finalizes through service-owned canonical credentials and per-ref serialization.
The client never receives canonical manifest/ref write or delete permission. Identical finalize retries return the recorded terminal result rather than committing twice.
Direct push
Unconfigured non-crab.build authorities retain the existing direct BYOC push
path. Direct pushes use five reusable repository-scoped admission objects,
weighted by configured worker width and the estimated xorb plus newly reachable
Git payload, to bound concurrent CPU, memory, and object-store pressure. A
single large push can reserve up to four payload slots, leaving one slot for
small work; an xorb client configured above 32 upload workers can reserve all
five. These slots provide repository workload fairness within one
cloud-credential trust domain; they do not identify or enforce quotas for
separate teams. Use a managed authority when authenticated organization-level
admission is required. Crab does not switch between managed and direct behavior
after a failure.
Options
| Option | Default | Description |
|---|---|---|
--upload-concurrency <N> | Configured value | Maximum concurrent xorb uploads |
--lock-wait-secs <SECONDS> | Configured value | Time to wait for contested direct-push locks |
--manifest-cas-retries <COUNT> | Configured value | Maximum direct manifest-CAS retries |
--rebase-on-non-fast-forward | Disabled | Integrate the current branch and retry after a non-fast-forward or lock conflict |
--rebase-retry-limit <COUNT> | 256 | Maximum integration attempts with automatic rebase enabled |
--dry-run | Disabled | Show what would be pushed without uploading |
-f, --force | Disabled | Bypass client fast-forward checks; server policy still applies |
-v, --verbose | Disabled | Show per-step timing and per-file progress |
--no-incremental | Disabled | Force a full graph walk |
--no-color | Disabled | Disable ANSI color |
--json | Disabled | Emit one terminal JSON envelope |
--jsonl | Disabled | Stream JSONL progress and a terminal result |
Examples
Push the current branch
crab pushPush a named branch
crab push origin feature-modelPush directly to a canonical managed URL
crab push crab://crab.build/acme/models mainDry run with structured output
crab push --dry-run --jsonStream progress for automation
crab push --jsonlFor git push, set CRAB_PROGRESS_FORMAT=jsonl to receive the equivalent
remote-helper event stream on stderr because Git owns helper stdout.