Pushing Changes

Use crab push after committing pointer files. It uploads missing chunk data from the local staging area to object storage, then pushes the Git ref.

crab add models/v2.safetensors
git commit -m "Add v2 checkpoint"
crab push origin main

For crab:// remotes, git push can also invoke Crab's remote helper. Prefer crab push when you want Crab-specific progress, structured output, or native concurrent upload behavior.

Use JSONL when a CI interface needs progress events and JSON when it needs one terminal envelope. In both modes, a nonzero exit status remains the publication failure signal.

Common Commands

What Happens

1. Crab finds pointer blobs in the commits being pushed.
2. It checks which chunks already exist remotely.
3. Missing chunks are packed into xorbs and uploaded.
4. The remote ref is updated only after required data is available.

Verify publication

Check the ref and repository closure after a successful push:

git ls-remote origin refs/heads/main
crab fsck --json
git status --short

The remote-ref hash should match the commit you intended to publish. The integrity check verifies referenced Crab objects rather than relying on the ref update alone, and the final Git status exposes local edits that were never part of the push.

These are separate boundaries: a ref can identify the expected commit while a referenced object is missing, and a complete remote push can coexist with new uncommitted local work. Record structured push and integrity output in CI when another job will hydrate the result.

Failure Recovery

• If upload fails, fix the cause and run crab push again. Already uploaded chunks are skipped.
• If a teammate cannot hydrate a file, run crab fsck locally and confirm the producing machine completed crab push.
• Use crab logs for detailed diagnostics when a push fails in CI.

For refspec handling, options, JSON/JSONL output, and edge cases, see the crab push reference.