How to fix error: split index base is outdated in Git

Understanding Split Index Internals:

The split index feature was introduced to speed up Git operations on repositories with large indexes. Every Git command that reads or writes the staging area (index) must process the entire index file. For repositories with tens of thousands of files, this becomes a bottleneck.

How Split Index Works:

1. Git creates a "shared index" ($GIT_DIR/sharedindex.<SHA-1>) containing most entries
2. A smaller "split index" ($GIT_DIR/index) stores only recent changes
3. Operations that only touch recently-changed files are faster
4. Periodically, Git merges changes back into a new shared index

The index file contains a "link" extension pointing to the base shared index. When this link references a SHA-1 that doesn't match an existing sharedindex file, you get the "split index base is outdated" error.

Why Third-Party Tools Fail:

Many Git libraries don't fully support split index:
- libgit2 (used by many GUI tools): Limited split index support
- GitPython: May crash on split index repositories
- gitui: Explicitly doesn't support split index
- JGit (Java): Partial support

If you use such tools, avoid enabling split index.

Compatibility with Other Features:

Split index cannot be used with:
- Sparse index (core.sparseIndex): These features are mutually exclusive
- Some Git hooks that directly manipulate the index

CI/CD Considerations:

If you're seeing this error in CI/CD:
1. Clean the workspace before checkout
2. Don't persist .git between builds
3. Use GIT_TEST_SPLIT_INDEX=0 environment variable to disable
4. Consider using shallow clones which avoid index complexity

Diagnosing the Problem:

To see what Git thinks about your index:

# Show index format version
git update-index --show-index-version

# View index entries (requires git-ls-files)
git ls-files --stage

Manual Recovery:

If nothing else works, you can recreate the repository state:

# Save your work
git stash
git diff > uncommitted.patch

# Create fresh clone
cd ..
git clone <remote-url> repo-fixed
cd repo-fixed

# Re-apply your work
git stash pop  # If you had stashed changes
git apply uncommitted.patch  # If you had uncommitted changes

Performance Considerations:

The split index provides meaningful speedup only when:
- Your repository has 5000+ files in the index
- You frequently modify a small subset of files
- Your storage is slow (spinning disks, network drives)

For SSD storage and smaller repositories, split index adds complexity without significant benefit.