Listing Tracked Files

When you need to see exactly which files Crab is managing in your repository — their names, sizes, content hashes, and whether they're hydrated or still pointers — crab ls-files gives you the full picture.

What It Shows

For each path matched by a filter=crab rule in .gitattributes, you can see:

• Content hash — The blake3 hash identifying this file version (from the pointer blob)
• Display state: whether Crab parsed a pointer or found full working-tree content
• File path — Relative path in the repository
• Size: current working-tree file size (with --size)

Basic Usage

crab ls-files

Hash        Status      File
──────────  ──────────  ────────────────────
abc1234567  pointer     models/weights.bin
def8901234  pointer     models/embeddings.bin
··········  unstaged    data/train.csv

pointer means the working-tree file itself contains a Crab pointer, so its content hash is available. The current human display labels matched full files as unstaged because no pointer can be parsed from their working-tree bytes. Use JSON when automation needs the explicit hydrated boolean. A full file can be a clean hydration or new content awaiting crab add; this listing alone does not distinguish those cases.

With File Sizes

crab ls-files --size

abc1234567  pointer       164 B  models/weights.bin
def8901234  pointer       164 B  models/embeddings.bin
··········  unstaged    45.2 MB  data/train.csv

The size column reports bytes currently on disk. For a pointer, that is the pointer blob size rather than the original managed file size.

Show file names only

For scripting or piping to other tools:

crab ls-files --name-only

models/weights.bin
models/embeddings.bin
data/train.csv

Common Patterns

Find all pointer files (not yet hydrated)

crab ls-files | grep ' pointer '

Count tracked files

crab ls-files --name-only | wc -l

Feed into hydration

crab ls-files --name-only | grep 'models/' | xargs crab hydrate

JSON for automation

crab ls-files --json | jq '.data.files[] | select(.hydrated == false) | .name'

Difference from crab status

Use status for a repository summary and ls-files when you need the full list.

CLI Reference

For complete command syntax, all output modes, and JSON format, see the crab ls-files reference.