LFS Compatibility

Use crab lfs when you need Git LFS pointers, hooks, or transfer-agent tooling while storing objects through Crab. LFS and Crab-native Xet files can coexist in one repository: choose the storage format explicitly with committed .gitattributes rules.

When to Use It

Crab does not guess between LFS and Xet from file size, extension, or content. The matching .gitattributes rule is authoritative. For example:

assets/releases/** filter=lfs diff=lfs merge=lfs -text
datasets/** filter=crab diff=crab merge=crab -text

Commit .gitattributes before adding files. A single git add may include paths from both groups: LFS paths bypass Xet staging, while Xet paths use chunking and xorb storage.

Common Commands

crab lfs install
crab lfs track '*.psd'
crab lfs fetch --include 'assets/**'
crab lfs pull
crab lfs status
crab lfs fsck

Migration Choices

• Use crab lfs migrate import --include '<pattern>' to convert regular files in history to LFS pointers.
• Use crab lfs migrate import --include '<pattern>' --from-crab to convert Crab pointers to LFS pointers.
• Use crab lfs migrate export --include '<pattern>' --to-crab to move LFS pointers into Crab-native storage.

History rewrites should happen on a branch with team coordination. After the rewrite, verify with crab lfs fsck and a fresh clone.

Verify the selected compatibility boundary

Check which pointer format is committed after tracking or migration:

git show HEAD:assets/model.psd | sed -n '1,4p'
crab lfs status
crab lfs fsck

An LFS pointer starts with the Git LFS specification URL, while a Crab pointer uses the Crab pointer specification. Do not infer the format from a .gitattributes rule alone; history can contain both formats during a staged migration. A fresh clone verifies that filter installation, transfer-agent configuration, remote objects, and checkout behavior agree for another client.

Pitfalls

• LFS compatibility does not replace the normal Crab workflow for new files.
• Tracking rules live in .gitattributes; commit those changes.
• Transfer-agent setup is Git config, so CI and collaborators may need crab lfs install.
• crab lfs install and crab lfs update fail if an unmanaged pre-push hook already exists. Merge crab lfs pre-push "$@" || exit $? into the hook manually, or use --force only when replacing it is intentional. Crab's own mirror hook is composed automatically.
• A Crab push verifies and publishes every reachable LFS object before making its Git ref visible. Missing or corrupt local and remote objects stop the push rather than publishing an incomplete ref.
• crab lfs prune --verify-remote downloads and verifies every candidate and is fail-closed. It does not delete an object that is missing or corrupt on the remote.
• Run crab lfs <subcommand> --help for exact flags before migration work.

For the current command list, see the crab lfs reference.