Reclaiming Local Cache Space

As you work with different branches and files, Crab's local cache accumulates objects you may no longer need. Pruning removes cached objects that aren't referenced by any pointer file in your current working tree, freeing disk space without touching the remote store.

How Pruning Works

Prune is purely local and always safe:

1. Walks your working tree and collects all content hashes from pointer files.
2. Walks the local cache directory (~/.cache/crab/ or $CRAB_CACHE_DIR).
3. Removes any cached object whose hash isn't in the referenced set.

The remote store always retains the authoritative copy. Pruned objects can be re-fetched anytime with crab hydrate.

Usage

Preview what would be removed

crab prune --dry-run

prune (dry run): would remove 15 objects (234567890 bytes)

Run the prune

crab prune

prune complete: removed 15 objects (234567890 bytes freed)

Verbose output (see each object)

crab prune --verbose

Extra safety: verify remote before deleting

crab prune --verify-remote

With --verify-remote, Crab confirms each object exists on the remote before deleting it locally. This prevents pruning objects that haven't been pushed yet.

When to Prune

Prune vs. GC

These are different operations at different scopes:

Cache Location

The local cache defaults to ~/.cache/crab/. Override with:

export CRAB_CACHE_DIR=/path/to/cache

CLI Reference

For complete command syntax and all available flags, see the crab prune reference.