crab add
Stage files for crab, bypassing git's serial filter protocol.
Synopsis
crab add [OPTIONS] <PATTERNS>...Description
crab add processes files matching the given glob patterns in parallel:
hashing, content-defined chunking (CDC), staging chunks locally, and writing
pointer files. It is significantly faster than git add for many large files
because it bypasses git's serial filter-process protocol and processes files
concurrently.
After chunking and staging, crab add writes Crab pointer blobs directly to
Git's object database and atomically replaces their index entries — unless
--skip-git-add is specified. Staged recipes become push-visible only after
that index transaction is durably reconciled. A later git add verifies the
incoming bytes against that prepared recipe and promotes an exact match without
repeating CDC, compression, payload reads, chunk-index writes, or a full-file
temporary spool. Concurrent crab add processes queue on the repository
staging lock instead of failing immediately.
For conceptual background on adding files and content-defined chunking, see Adding Files.
Arguments
| Argument | Required | Description |
|---|---|---|
patterns | Yes | One or more glob patterns to match files (e.g. *.safetensors, models/) |
Options
| Option | Short | Default | Description |
|---|---|---|---|
--jobs | -j | 16 | Maximum number of concurrent file-processing tasks |
--dry-run | false | Show what would be added without staging or writing pointers | |
--skip-git-add | false | Prepare local staging only; do not publish pointer index entries or recipes | |
--json | false | Emit a single JSON envelope with the result | |
--jsonl | false | Stream JSONL output (one event per line) |
Examples
Add all safetensors files
crab add '*.safetensors'Add files from a specific directory
crab add 'models/*'Add with higher parallelism
crab add -j 16 '*.bin' '*.safetensors'Dry run to preview what would be staged
crab add --dry-run '*.bin'Prepare staging without changing Git's index
crab add --skip-git-add '*.bin'
git add models/weights.bin # promotes the exact prepared recipe laterOutput
Added 5 files (2.3 GB total, 847 chunks)
models/weights.bin 1.2 GB 423 chunks
models/embeddings.bin 800 MB 312 chunks
data/train.safetensors 300 MB 112 chunks
...In dry-run mode, the output is prefixed with (dry run) and no files are
modified.
Pattern Syntax
crab add uses git's pathspec syntax (gix-pathspec):
*.bin— matches files ending in.binanywhere in the treemodels/**— matches every path undermodels/:(exclude)*.tmp— excludes.tmpfiles from the result:(glob)models/**.bin— force glob semantics:(icase)README.md— case-insensitive match
Multiple patterns compose: crab add 'models/**' ':(exclude)models/archive/**'
JSON Output
--json emits one terminal result envelope. --jsonl streams progress events
and ends with a result event. See Structured Output
for envelope details, event types, and error handling.
Related Commands
crab track— register file patterns for crab tracking.crab reset— unstage files and clean staging data.crab status— see hydration state of tracked files.crab staging— inspect the staging area.