How do you move a Git LFS repository to Crab?

Suppose models/encoder.safetensors is an 8 GB LFS file used by developers, CI, and old release tags.

Crab gives that repository two paths:

• Bridge: keep the LFS pointer and commit IDs; invoke Crab's local standalone transfer agent, which accesses the Crab object store directly.
• Convert: replace selected LFS pointers with native Crab pointers; rewrite affected commits.

These are different migrations. Pick the boundary before picking the command.

version https://git-lfs.github.com/spec/v1
oid sha256:91ae…b72c
size 8589934592

First, prove the source is complete

Use a disposable clone. Do not learn that an old object is missing halfway through a rewrite.

git status --short
git remote -v
git lfs ls-files
crab lfs migrate info --pointers only --everything

Check four things:

Hash a few representative files now. After migration, a fresh client should produce the same bytes.

shasum -a 256 models/encoder.safetensors

Signed commits and tags need a separate plan: rewritten Git objects get new IDs, so old signatures no longer describe them.

Path 1: keep LFS semantics, change the route

Install Crab as Git LFS’s custom transfer agent:

crab lfs install
crab lfs env
crab lfs fetch
crab lfs checkout
crab lfs fsck

install configures the local transfer agent, LFS filters, and a pre-push gate. Crab does not deploy an LFS gateway. Git still commits the standard LFS pointer:

version https://git-lfs.github.com/spec/v1
oid sha256:91ae…b72c
size 8589934592

That means:

• existing commits keep their IDs;
• tools that require LFS pointers can keep using them;
• rollback is a configuration change, not a ref rewrite;
• the stored unit is still the whole LFS object.

The last point matters. The bridge changes transport and ownership, but it does not turn an LFS object into Crab chunks. A slightly changed 8 GB model still has a new whole-file LFS object ID.

Test both directions. Push one new LFS object, then fetch it from a disposable clone with an empty local LFS cache. Reading old data alone does not prove that new writes use the Crab route.

Also test one machine without the Crab configuration. Decide whether that client should keep using the old endpoint or fail with a clear bootstrap instruction. An accidental mixed-client period is not a migration plan.

To remove Crab’s transfer configuration later:

crab lfs uninstall

Keep the previous LFS endpoint available until supported refs no longer depend on it.

Path 2: convert to native Crab pointers

Use native conversion when chunk reuse, native hydration, and Crab’s storage layout justify new Git identities.

crab lfs migrate export \
  --include '*.safetensors' \
  --to-crab \
  --everything \
  --object-map ../lfs-to-crab.csv

For every matched LFS blob, Crab resolves the original bytes, creates native content and metadata, replaces the blob with a Crab pointer, updates tracking rules, and rewrites descendants.

version https://crab.dev/spec/v1
file-hash 4cb9…731a
size 8589934592

The object map records old and new commit IDs. Keep it outside the rewritten clone so it survives a reset or replacement clone.

A path pattern limits which blobs convert. Ref selection limits which history is rewritten. They solve different problems.

If the model first appears in commit B, converting that blob changes B and every selected descendant—even commits that never touch the model again. Branch protections, release records, submodules, and open work may all name the old IDs.

Partial conversion is possible, but it leaves two pointer systems in supported history. Document exactly which paths and refs remain LFS-backed, or choose one clean boundary.

Rehearse the failure, not just the command

Use an isolated Crab destination and the same branch/tag scope planned for production.

A useful rehearsal has observable gates:

1. Fetch the selected refs and resolve every required LFS object.
2. Run the bridge or conversion against a separate destination prefix.
3. Push to an isolated remote namespace.
4. Clone with an empty cache on another machine or runner.
5. Materialize files from the default branch and an old release tag.
6. Compare hashes, run the real workload, and record old/new commit IDs.

For a native conversion, verify the repository as well as sample bytes:

git log --all --oneline --decorate
crab status
crab fsck

Check that every selected ref exists at its mapped ID, parent relationships preserve the intended topology, tracking rules match each historical pointer format, and every remaining LFS pointer still has a supported source.

Byte equality proves the migration copied data correctly. A build, training smoke test, or model load proves automation still finds it.

Cut over only after an independent client passes

The bridge can roll out gradually if every supported client has the transfer configuration. A native rewrite needs a write freeze and one coordinated publication event.

For native cutover:

1. Announce the freeze and preserve the final old refs.
2. Run the rehearsed conversion from the final production state.
3. Verify hashes, topology, attributes, and object closure.
4. Publish mapped refs under the agreed protection exception.
5. Update CI, release records, branch protections, and submodule references.
6. Have an independent clean client hydrate and run the workload.
7. Reopen writes only after that client passes.

Contributors with unpushed work need a backup ref and a deliberate rebase or cherry-pick onto mapped history. Avoid blanket “force pull” instructions: they can destroy unrelated work.

Retire the old endpoint later

A successful migration proves the new path. It does not authorize immediate deletion of the old LFS objects.

Keep the old refs, object inventory, and commit map through the rollback window. Remove old storage only after supported tags, CI, releases, and contributor recovery no longer need it—and run that deletion through its own preview and approval.

See the crab lfs reference for exact options before a rehearsal.