Adding Files

Use crab add when a file should be stored by Crab instead of directly in Git. It chunks matching files, deduplicates the content, stores new chunks in .crab/staging/, and stages pointer blobs in Git.

crab add models/checkpoint.safetensors
crab add 'data/*.parquet'
crab add .

When to Use It

Run crab track <glob> first for reusable patterns, then commit the resulting .gitattributes change so collaborators use the same rules.

--dry-run reports the candidate set without changing the Git index or Crab staging. Use it before a directory-wide add when ignore and tracking patterns overlap.

After Adding

crab status
crab ls-files --size
git diff --cached
git commit -m "Add dataset"
crab push origin main

crab add stages Crab pointer blobs for Git. Keep using normal Git commands for review and commits.

Verify both staged layers

Crab staging and the Git index represent different parts of the same pending change. Check both before committing:

crab staging verify
git show :models/checkpoint.safetensors
git status --short

The staging verification checks the local file metadata and chunk payloads. The git show :<path> command reads the index entry and should display a small Crab pointer rather than the full binary content. git status confirms which paths and tracking-rule changes will enter the commit.

If verification fails, do not commit an incomplete pointer. Use crab reset to remove the selected paths from both staging layers, correct the source or configuration, and add them again.

Common Pitfalls

• Shell globs can expand before Crab sees them. Quote patterns like crab add '*.bin' when you want Crab to match them.
• crab add is local until you push. The staged chunks stay in .crab/staging/ until crab push uploads them.
• If a file is not matched, check .gitattributes and crab track --list.
• Re-run crab add after changing a large file before committing.

For complete syntax, flags, path matching details, and JSON/JSONL output, see the crab add reference.