Index versions

Git's index has had several formats. Version 2 is the historic baseline. Version 3 added skip-worktree and other extensions. Version 4 (recommended for large repos) adds prefix compression of paths, halving index size on deep trees. Version 4 became default in Git 2.37+ for new repos via feature.manyFiles.

Setting

git config index.version 4
git update-index --index-version 4

The first sets the policy; the second rewrites the existing index file in the new format. Run both for an existing repo.

Why version 4 helps

For monorepos with deep paths like apps/web/src/components/foo/bar/baz/Quux.tsx, repeated path prefixes dominate index size. V4 stores each path as a delta from the previous, shrinking the index 30-60% on real monorepos. Smaller index = faster read/write = faster every command.

Inspecting

git ls-files --debug | head
ls -la .git/index
GIT_TRACE2_PERF=1 git status 2>&1 | grep "do_read_index"

The trace timing for index read/write reveals the impact directly.

Pair with feature.manyFiles

git config feature.manyFiles true

This single setting enables index.version=4, core.untrackedCache=true, and other monorepo-friendly defaults. See "Feature.manyFiles configuration".

When not to

For small repos (under 10k files), v2 is fine; the difference is invisible. Some old third-party tools that read the index directly may not understand v4 — check libgit2 1.5+ or update.

Common mistakes

Setting index.version in config but not running git update-index --index-version — the next index write picks up the new version, but until then, the on-disk file stays at the old format. Mixing V4 with old fork tools: lock to current Git for the team.

Side note: skip-worktree and assume-unchanged

These bits live in the index. V3+ supports them; V2 has limited support. Sparse checkout uses skip-worktree heavily, so V3+ is required for cone mode.

Related

See "Feature.manyFiles configuration", "Git internals: the index format", and "The sparse index: operating without a full index".