Reclaiming Local Cache Space
As you work with different branches and files, Crab's local cache accumulates chunks, xorbs, and shards. Pruning evicts the least-recently-used cache objects until the cache fits its configured budgets, freeing disk space without touching the remote store.
How Pruning Works
Prune is purely local and never mutates the configured remote:
- Walks the local cache directory (
~/.cache/crab/or$CRAB_CACHE_DIR). - Sorts chunk/xorb objects by least-recently-used order under the shared data-object budget.
- Sorts shard objects by least-recently-used order when a shard budget is configured.
- Removes the oldest objects needed to bring the cache back under budget.
The remote store is the authoritative copy. Pruned objects can be fetched again when the remote remains reachable and still contains the referenced data.
Usage
Preview what would be removed
crab prune --dry-runprune (dry run): would remove 15 objects (234567890 bytes)Run the prune
crab pruneprune complete: removed 15 objects (234567890 bytes freed)Verbose output (see each object)
crab prune --verboseWhen to Prune
| Scenario | Why it helps |
|---|---|
| After heavy hydrate/fetch work | Trims oldest cached data back to budget |
| Disk space is low | Reclaims cache space without affecting the remote |
| Periodic maintenance | Keeps the cache lean over time |
Prune vs. GC
These are different operations at different scopes:
crab prune | crab gc | |
|---|---|---|
| Scope | Local cache only | Remote store |
| Safety | Remote is untouched; later reads may need network access | Requires careful reference checking |
| Reversibility | Objects re-fetched on next hydrate | Deleted objects are gone permanently |
| When to use | Free local disk space | Remove unreachable remote objects |
Cache Location
The local cache defaults to ~/.cache/crab/. Override with:
export CRAB_CACHE_DIR=/path/to/cacheVerify reclaimed space
Compare the dry-run plan with the terminal result and a new usage report:
crab prune --dry-run --json
crab prune --json
crab duThe removed-object count can differ if cache access or another Crab process
changes recency between plan and apply. After pruning, hydrate one representative
file to confirm the configured remote can refill missing cache objects. Use
crab cache clean only when you intend to remove the full local cache rather
than enforce its budgets.
CLI Reference
For complete command syntax and all available flags, see the crab prune reference.