Use Crab LFS directly

Crab LFS is the compatibility path for repositories that need standard Git LFS pointers, existing filter=lfs rules, or tools that already call

git lfs. It does not require a Git LFS server, HTTP gateway, or Crab service.

Install Crab on each developer machine or CI runner. Crab then reads and writes the configured S3, GCS, Azure, or S3-compatible bucket directly.

Choose the path you actually need

Do not choose crab lfs solely because a file is large. The tracking rule decides the representation:

Keep the two rules separate when a repository needs both:

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

If your repository already contains LFS pointers, keep those pointers and use the direct transfer path below. If you want Crab's chunk-level deduplication, read the native Crab workflow instead.

Set up a direct Crab LFS repository

Run this once from the repository root. The crab:// URL identifies a bucket and repository prefix; --storage-provider s3 selects the S3-compatible client.

crab init --storage-provider s3 crab://team-bucket/model-repository
crab lfs install --local
crab lfs track '*.safetensors'
crab lfs track '*.bin'

git add crab.toml .gitattributes
git commit -m "Configure direct Crab LFS"
git push origin main

crab lfs install configures three local Git boundaries:

• filter.lfs.clean and filter.lfs.smudge use Crab for pointer conversion.
• lfs.standalonetransferagent=crab lets an unmodified Git LFS client invoke Crab's transfer agent.
• A pre-push hook uploads missing LFS objects before the Git ref is published.

The configuration is local. Commit .gitattributes, not

.git/config or any credential. If an existing unmanaged pre-push hook is present, Crab stops and prints the merge command; use --force only when replacing that hook is intentional.

Use it every day

After setup, the normal Git loop remains unchanged:

cp /path/to/encoder-v2.safetensors models/encoder.safetensors
git add models/encoder.safetensors
git commit -m "Update encoder"
git push origin main

Git stages a small standard LFS pointer while the full file stays in the local LFS cache. The Crab pre-push hook uploads the missing object directly to the bucket, then the Crab remote helper publishes the commit.

If you prefer explicit Crab commands, the same boundaries are visible here:

crab lfs status
crab lfs push origin main
crab lfs fsck HEAD

Clone and retrieve files

Clone the Git history, install the local LFS integration, then choose when to materialize large files:

git clone crab://team-bucket/model-repository model-repository
cd model-repository

crab lfs install --local --skip-smudge
crab lfs pull origin

The --skip-smudge option leaves pointers in the worktree until you request content. Fetch or materialize selectively when the repository is larger than the machine's local disk:

crab lfs fetch origin --include 'models/**'
crab lfs checkout 'models/**'

With Git LFS installed, the equivalent standard command is:

git lfs pull origin main

Without Git LFS installed, use crab lfs pull origin instead. Both commands use the same direct object-storage route after

crab lfs install.

Verify the boundary before production

Check the local wiring first:

crab lfs env
git config --local --get lfs.standalonetransferagent
git config --local --get lfs.customtransfer.crab.path
git check-attr filter -- models/encoder.safetensors

Expected results include StandaloneTransferAgent=crab,

lfs.customtransfer.crab.path pointing to the Crab binary, and filter: lfs for the tracked model path.

Then prove the full path with a disposable object-storage prefix:

1. Add a representative file and confirm git cat-file -s :path is only a small pointer.
2. Run git lfs push origin main or crab lfs push origin main and inspect the bucket's lfs/objects/ prefix.
3. Clone with an empty local LFS cache.
4. Run git lfs pull origin main or crab lfs pull origin.
5. Compare the recovered file's SHA-256 with the pointer OID.
6. Finish with crab lfs fsck HEAD.

For a copy-paste RustFS check using local credentials and a disposable prefix, see the interactive Crab LFS guide and the S3-compatible credentials guide.

Know the compatibility boundary

Crab supports the direct-storage standalone transfer-agent profile. It does not expose the standard Git LFS HTTP Batch API and does not ask you to deploy a gateway. Point the repository at a crab:// remote, install Crab locally, and grant the client scoped access to the object-storage prefix.

For the full command list, migration behavior, locking, pruning, and failure handling, read the crab lfs reference and the LFS compatibility guide.