git merge-index

How merges actually wire conflicts into the index.

🎯 What & why

git merge-index walks unmerged entries in the index and runs a merge program for each, letting you script how stage 1/2/3 entries get reconciled. It's the dispatcher under git merge.

🧠 Mental model

After a merge attempt, the index holds up to three stages per conflicted path. merge-index feeds those stages plus the path to a per-file merge driver and updates the index based on its result.

🛠️ Synopsis

git merge-index [-o] [-q] <merge-program> (-a | [--] <file>...)
git merge-index [-o] [-q] <merge-program> --stdin [-z]

🎚️ Switches & options

Flag	What it does
`<merge-program>`	Program to invoke per file; gets stages and path as arguments.
`-a / --all`	Run the merge program for every unmerged entry in the index.
`-q / --quiet`	Don't complain when the merge program exits non-zero.
`-o / --one-shot`	Continue past failures and report at the end instead of stopping on first error.
`--stdin`	Read paths to merge from stdin instead of arguments.
`-z`	With --stdin, expect NUL-terminated paths.

💡 Use cases

Scripting custom resolution after a low-level git read-tree -m 3-way read.
Wiring git merge-one-file (or your own driver) across many conflicted paths.
Building merge tools that iterate the index rather than the working tree.
Batch-resolving conflicts in CI with a deterministic policy.

🧪 Examples

Run git's default driver on all conflicts

git merge-index -o git-merge-one-file -a

Resolve a single file via custom driver

git merge-index ./my-driver.sh -- path/to/conflicted

Stream paths from stdin (NUL-separated)

git diff --name-only -z --diff-filter=U | git merge-index -o git-merge-one-file --stdin -z

Quiet, keep going on errors

git merge-index -q -o git-merge-one-file -a

🎓 Recommendations

Use git merge-one-file as the standard driver unless you have a strong reason to roll your own.
Combine -o with explicit exit-code checks; you want to know which files still need help.
Drive it from git ls-files -u output for full control over what gets retried.

🪤 Common pitfalls

Without -o, merge-index stops at the first driver failure, leaving the rest unresolved.
The merge program receives stage SHAs, not file contents; your driver must cat-file them itself.
It only operates on entries already in the index; you must read-tree -m first to populate stages.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.