git merge-one-file

What .gitattributes merge=union etc. dispatches to.

🎯 What & why

Internal three-way merge driver invoked per-file. This is what merge=union and friends in .gitattributes dispatch to, called by git merge-index once for every conflicted path.

🧠 Mental model

Plumbing-level, single-file merge: given three blob/mode/SHA triples (base, ours, theirs) and a path, write the merged result into the working tree and stage it (or report a conflict).

🛠️ Synopsis

git merge-one-file <orig-blob> <our-blob> <their-blob> <path> <orig-mode> <our-mode> <their-mode>

# Actually invoked indirectly:
git merge-index git-merge-one-file -a
git merge-index -o git-merge-one-file <paths>...

🎚️ Switches & options

Flag	What it does
`(positional) orig-blob`	SHA of the common ancestor blob, or empty string if absent
`(positional) our-blob`	SHA of HEAD's version of the blob
`(positional) their-blob`	SHA of MERGE_HEAD's version
`(positional) path`	Working-tree path to write the merged result to
`(positional) modes`	Three octal mode strings (orig, our, their); blank means missing

💡 Use cases

Underlies git merge-index -a when finishing an index-level merge
The default driver dispatched by .gitattributes merge=text (the implicit setting)
Reference implementation when writing a custom driver via merge.<name>.driver
Debugging why a particular file produced a conflict during a stuck merge

🧪 Examples

Re-run the merge driver for everything still conflicted

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

Drive merges only for two specific paths

git merge-index -o git-merge-one-file src/a.c src/b.c

git config merge.ourunion.driver 'cat %A %B > %A'

Activate it for a path via gitattributes

echo 'CHANGELOG merge=ourunion' >> .gitattributes

🎓 Recommendations

You almost never call this directly; reach for git merge-index or just git merge instead.
Custom drivers receive %O %A %B %L %P placeholders (ancestor, ours, theirs, marker size, path) - mirror that contract.
Exit nonzero from a custom driver to signal an unresolved conflict; zero means resolved and staged.

🪤 Common pitfalls

An empty argument means 'blob/mode absent' - not the literal empty string. Forgetting that breaks custom drivers.
It writes directly to the working tree path; running it manually on a clean checkout will scribble over files.
The driver name text is implicit; defining merge.text.driver overrides Git's built-in three-way merge globally.

🔗 Related modules

📝 Quiz

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