git merge-file

Merge engine you can drive on arbitrary files outside a repo.

🎯 What & why

git merge-file performs a 3-way merge on three arbitrary files (current, base, other) and writes the result. It's Git's merge engine exposed for scripts and external diff tools.

🧠 Mental model

Think diff3 with conflict markers and Git semantics. No repo required; you point it at three paths and it produces a merged file plus an exit code equal to the number of conflicts.

🛠️ Synopsis

git merge-file [-L <cur> [-L <base> [-L <other>]]] [--ours|--theirs|--union]
               [-p] [-q] [--marker-size=<n>] [--diff-algorithm=<algo>]
               <current-file> <base-file> <other-file>

🎚️ Switches & options

Flag	What it does
`-p`	Write the merged result to stdout instead of overwriting <current-file>.
`-q`	Quiet: suppress conflict warnings on stderr.
`-L <name>`	Label for current/base/other (repeat up to 3x); shows up in conflict markers.
`--ours`	On conflict, take the current side; no markers emitted.
`--theirs`	On conflict, take the other side; no markers emitted.
`--union`	Concatenate both sides on conflict; no markers, but may produce nonsense.
`--marker-size=<n>`	Change the length of <<<<<<< markers (default 7).
`--diff-algorithm=<algo>`	Pick myers, minimal, patience, or histogram.

💡 Use cases

Scripted merges of generated files (configs, fixtures) without committing intermediate state.
Driving a custom merge tool that needs the raw 3-way result.
Building merge-resolution UIs on top of Git's engine.
Resolving conflicts in detached working trees or non-Git content.

🧪 Examples

Standard 3-way merge in place

git merge-file -L mine -L base -L theirs cur.txt base.txt other.txt

Preview to stdout, keep originals

git merge-file -p cur.txt base.txt other.txt

Auto-resolve favoring our side

git merge-file --ours cur.txt base.txt other.txt

Histogram diff for code-like content

git merge-file --diff-algorithm=histogram cur.c base.c other.c

🎓 Recommendations

Always set -L labels; default labels in conflict markers are unhelpful in scripts.
Check the exit code: 0 = clean, N>0 = number of conflicts, <0 = error.
Use --diff-algorithm=histogram for source code; it produces fewer spurious conflicts than myers.

🪤 Common pitfalls

By default <current-file> is overwritten in place; use -p to avoid clobbering.
--union 'resolves' conflicts by gluing both sides together; great for changelogs, terrible for code.
Exit code is the conflict count, not 0/1; naive && chains misbehave.

🔗 Related modules

📝 Quiz

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