Sparse-checkout and filter — only what you need

Sparse-checkout restricts the working tree to a subset of paths; filter restricts the packfile. Each is a performance optimisation, never an isolation mechanism. CODEOWNERS is the ownership mechanism.

The five sparse-checkout commands

git sparse-checkout init --cone
git sparse-checkout set "services/payments"
git sparse-checkout add "services/billing"
git sparse-checkout list
git sparse-checkout disable

init --cone enables cone mode (only one that scales). set replaces; add appends; list shows; disable removes.

flowchart LR
    A[packfile] -->|"sparse"| B[("subset tree")]
    A -->|"filter blob:none"| C[("defer blobs")]
    A -->|"sparse + filter"| D[("small + on-demand")]

The mechanisms are independent: sparse restricts the working tree; filter restricts the packfile.

Cone mode versus pattern mode

Cone mode (--cone) restricts by directory. Pattern mode allows globs but is O(history) per op and does not scale. Always use --cone; pattern mode is for backward compatibility only.

Combining with --filter

REPO_URL="https://github.com/example/monorepo.git"

git clone --filter=blob:none "$REPO_URL" repo
cd repo
git sparse-checkout init --cone
git sparse-checkout set "services/payments"
git ls-files | wc -l

The four commands: partial clone, init, set, verify. ls-files | wc -l should report a small count, not the full repo size.

Verification

git ls-files | wc -l
git sparse-checkout list

ls-files | wc -l should report a small count. list shows the allow-list; if empty, init was not run. A common failure is init without --cone, which succeeds but produces the unusable shape.

Production discipline

1. Always --cone. Pattern mode does not scale.
2. Verify with git ls-files | wc -l. A large count means the sparse-checkout is not active.
3. Treat as performance, not isolation.
4. Combine with --filter=blob:none for working trees.

Cross-course references

• Linux for Production Sysadmins Part XXVI: bind-mounted subtrees.
• Terraform for Production Sysadmins Part IX: workspace directories.

Quiz