How does Crab connect to Git?

Crab does not patch Git. Git calls it through two standard extension points:

• A filter process turns a tracked file into a pointer during add, then turns that pointer back into file bytes during checkout.
• A remote helper handles fetch and push for crab:// remotes.

Follow one model through Git

vision-search/
├── src/train.py
└── models/encoder.safetensors  # 8 GB

The Python file stays an ordinary Git blob. The model takes a second data path, but both paths still belong to one commit.

1. Add calls the clean filter

First, select the model path:

crab track '*.safetensors'
git add .gitattributes
git check-attr filter -- models/encoder.safetensors

crab track writes this rule:

*.safetensors filter=crab diff=crab merge=crab -text

Git's filter attribute decides which file content crosses the clean/smudge boundary. The check should report filter: crab.

Now use Git's add path so the filter boundary is visible, then inspect Git's copy:

git add models/encoder.safetensors
git show :models/encoder.safetensors

The worktree still holds 8 GB. Crab streams those bytes through hashing and content-defined chunking, saves the ordered recipe in local staging, and gives Git a compact pointer.

For many large files, crab add reaches the same index and staging state through Crab's parallel native path instead of Git's serial filter requests. The trace below shows that optimized route.

The staged blob has this shape:

version https://crab.dev/spec/v1
file-hash <64-hex BLAKE3>
size 8589934592

An optional shard hint may also appear. It can speed lookup, but the file hash remains the identity Crab verifies.

Git now has two IDs for two different things:

If Crab cannot stage a complete recipe, clean returns an error. It does not hand Git a pointer that only looks valid.

2. Push calls the remote helper

Git sees a URL such as crab://team-data/vision-search and looks for git-remote-crab. That follows Git's standard remote-helper contract: helpers advertise capabilities, list refs, and handle fetch or push batches over standard input and output.

git remote get-url origin
git commit -m "Train encoder v1"
git push

The helper finds every pointer reachable from the proposed branch. It prepares two immutable lanes:

• Git commits, trees, and pointer blobs become a Git pack.
• New chunks and reconstruction metadata become xorbs and shards.

The ref moves only after both lanes pass closure checks. crab push reaches the same repository outcome through Crab's native concurrent pipeline rather than Git's helper loop.

Local staging connects clean to push. Clean does not know which branch or remote will use the pointer, so it keeps the recipe and new bytes until publication. After a successful push, another client can reconstruct the file from canonical remote state.

To confirm the visible result:

git rev-parse HEAD
git ls-remote origin "refs/heads/$(git branch --show-current)"

The two commit IDs should match.

3. Fetch moves Git history first

On another client:

git fetch origin
git show FETCH_HEAD:models/encoder.safetensors

git fetch asks the helper to list refs and import the required Git packs. The model arrives as its pointer blob. Fetch does not need to download 8 GB just to let Git inspect the commit.

This distinction is useful when debugging:

• If Git cannot see the commit, inspect the remote helper.
• If Git sees the pointer but cannot rebuild the model, inspect Crab metadata and object access.

4. Checkout calls the smudge filter

During checkout, Git sends the stored blob to smudge. Ordinary blobs pass through unchanged. A Crab pointer can remain a pointer for a lazy checkout or resolve to complete file bytes.

git checkout FETCH_HEAD -- models/encoder.safetensors
crab status
crab hydrate models/encoder.safetensors

crab hydrate makes the read path explicit: resolve the recipe, locate every chunk, plan object-store ranges, reconstruct in order, and verify the final BLAKE3 hash before replacing the pointer.

Two clients can therefore check out the same commit with different local working sets. The committed pointer does not change.

Why the filter stays alive

Git's long-running filter process handles many paths during one Git command. Git and Crab first agree on protocol version 2 and the supported operations:

git-filter-client
version=2
capability=clean
capability=smudge
capability=delay

Keeping one process alive avoids starting Crab and reopening indexes for every model. Each path still receives its own status and content response.

The optional delay capability lets checkout continue while eligible files reconstruct in the background. It changes scheduling, not integrity: the final result is complete verified bytes or an error.

Protocol output belongs to Git. Human debug text on standard output can break packet or line framing, so Crab sends diagnostics through its logging boundary.

One file, two extension points

The pointer is the handoff. Clean creates it with local backing state; the helper publishes it with durable backing state; hydration uses it to verify the returned bytes.

Debug the first broken boundary

git check-attr filter -- models/encoder.safetensors
git show :models/encoder.safetensors
git remote -v
git ls-remote origin
crab status
crab doctor
crab fsck

Start with the earliest failed check. Changing the remote helper cannot repair a path that never entered clean, and changing the filter cannot repair a missing remote xorb.

Source map

Continue with How do you work with Crab after the first push? to turn these integration points into a repeatable team workflow.