Skip to content

Sparse Index Quick Reference ​

Core Commands ​

# Enable (Git 2.32+)
git sparse-checkout init --cone --sparse-index

# Toggle without re-init (Git 2.37+)
git sparse-checkout sparse-index enable
git sparse-checkout sparse-index disable

# Check status
git config index.sparse

# Re-collapse after auto-expansion
git sparse-checkout reapply

Inspection ​

# Total index entries
git ls-files --stage | wc -l

# Sparse directory count
git ls-files --stage | grep '^040000' | wc -l

# List sparse directories
git ls-files --stage | grep '^040000'

# Expanded view (includes sparse dir contents)
git ls-files --sparse --stage

CI Patterns ​

# Fast clone + sparse index (Git 2.32+)
git clone --filter=blob:none --sparse <url>
git sparse-checkout set --cone <path>

# CI lint — fail if index is fully expanded
assert_sparse_index() {
  local c; c=$(git ls-files --stage | grep '^040000' | wc -l)
  [ "$c" -gt 0 ] || { echo "FAIL: sparse index not active"; exit 1; }
}

# Post-clone health check
total=$(git ls-files --stage | wc -l)
sparse=$(git ls-files --stage | grep '^040000' | wc -l)
echo "Index: $total entries ($sparse sparse dirs)"

Commands That Auto-Expand ​

CommandRe-collapse Since
git merge2.34
git rebase2.35
git cherry-pick2.34
git revert2.34
git stash2.36
git bisect2.36
git read-tree -m2.35

Version Check ​

git --version
# Need 2.32+ for sparse index

Pitfalls ​

  • Scripts parsing git ls-files --stage expecting only 100644/100755 will break on 040000 sparse directory entries — add --sparse or handle the directory mode.
  • Auto-expansion is transparent but has a cost — batch merge operations before the index re-collapses.
  • Sparse index is nearly always beneficial, but repos under ~10k files see minimal gain.

Git Master — Git Reference for Every Skill Level