Technology · PRACTICAL GUIDE
Git says “index file corrupt”? Prove which index failed before deleting it
A corrupt staging index, a linked-worktree index, a split or sparse index, and a pack .idx file are different failures. Preserve any readable staged ledger, resolve the exact path, rebuild only that class, then verify objects and repeat the original workflow.
A corrupt staging index, a linked-worktree index, a split or sparse index, and a pack .idx file are different failures. Preserve any readable staged ledger, resolve the exact path, rebuild only that class, then verify objects and repeat the original workflow.
The worktree index records staged entries and is separate from the object database. A .git entry can be a file pointing to the real gitdir, so .git/index is not universal.
1. Freeze the exact error path and preserve staged evidence
Save the complete error, current directory, command and timestamp. If Git can still read the index, export git diff --cached --binary and git ls-files --stage. Copy the named index before any reset. A staged change may not exist in the working tree exactly as staged, so a later restage is not always equivalent.
Do not start with rm -f .git/index. The error may name another worktree index or objects/pack/*.idx, and unconditional deletion can erase the best remaining evidence about staged intent.
2. Resolve the real gitdir, worktree and index identity
Run git rev-parse --show-toplevel, --git-dir, --git-common-dir and --git-path index from the same shell and environment that failed. A .git file may redirect to another directory, and a linked worktree keeps per-worktree state outside the visible checkout root.
Record GIT_DIR, GIT_WORK_TREE and GIT_INDEX_FILE if set. Compare the failing path with the resolved index. If they differ, stop and classify the named file rather than applying a generic worktree-index recipe.
3. Classify worktree, split or sparse index versus pack index
The ordinary worktree index is the staging ledger. Split-index mode adds sharedindex.<hash>; sparse checkout uses skip-worktree bits and may use a sparse index. Preserve config and git sparse-checkout list output before rebuilding.
A path under objects/pack ending in .idx indexes a pack of Git objects. Deleting the staging index will not repair it. Protect the pack pair, verify the object store and use object-database recovery or a fresh clone instead of mixing the two procedures.
4. Rebuild only the proven index class
For a proven corrupt worktree index, move the file aside instead of erasing it, then rebuild from HEAD with git reset --mixed from the correct worktree. This preserves working-tree files but clears staged state; use the saved cached diff and stage list to reconstruct intent carefully.
For split or sparse state, restore the supported sparse-checkout configuration and reapply it after the base index is readable. Do not delete sharedindex files or disable sparse checkout merely to make status run without first recording the mode.
5. Verify objects, staged intent and same-environment recurrence
Run git status, inspect git diff and git diff --cached, and use git fsck --full to check commits, trees and blobs. Confirm that newly added files and staged-only hunks were either recovered or explicitly restaged from evidence.
Repeat the original status, checkout or CI workflow in the same filesystem, worktree and sandbox. If corruption returns, investigate storage health, abrupt termination, overlapping writers, antivirus or overlay behavior; a successful one-time reset is not proof that the cause is gone.
