git merge-tree

What would happen if I merged X into Y? Without touching either.

🎯 What & why

git merge-tree performs a trial three-way merge in memory and reports the resulting tree (and conflicts) without touching the index, working tree, or any branch. It answers 'would this merge cleanly?' for tooling and humans alike.

🧠 Mental model

A pure function: (base, ours, theirs) -> (tree, conflict list). No refs move, no files change; modern hosted platforms call this to compute mergeability badges.

🛠️ Synopsis

git merge-tree [--write-tree] [--merge-base=<commit>]
               [--no-messages] [--name-only] [-z]
               <branch1> <branch2>

🎚️ Switches & options

Flag	What it does
`--write-tree`	Modern mode: actually compute and write the merged tree, return its OID.
`--merge-base=<commit>`	Override the auto-detected merge base.
`--no-messages`	Suppress informational conflict messages; just emit the data.
`--name-only`	Output only conflicting paths, not full conflict info.
`-z`	NUL-terminate path output for safe scripting.

💡 Use cases

Pre-flighting a merge from CI before opening a PR, so the bot can label it 'will conflict'.
Computing the merged tree OID for a virtual preview without polluting any branch.
Scripting bulk mergeability scans across many topic branches against main.
Producing a list of conflicting paths to feed into review tooling.

🧪 Examples

Trial merge, write the resulting tree

git merge-tree --write-tree feature main

Just the conflicting paths, NUL-separated

git merge-tree --write-tree --name-only -z feature main

Force a specific merge base

git merge-tree --write-tree --merge-base=abc123 feature main

Quiet mode for tooling

git merge-tree --write-tree --no-messages feature main

🎓 Recommendations

Always use --write-tree on modern git; the legacy positional form is being phased out.
Pair --name-only -z when piping into xargs or another script; whitespace in paths will bite you otherwise.
Treat a non-zero exit as 'conflicts present', not as 'command failed'; check stderr for real errors.

🪤 Common pitfalls

The old 3-arg form (base, ours, theirs) is still accepted but deprecated; mixing it with --write-tree confuses people.
It does not run merge drivers from .gitattributes the same way a real merge does in every edge case.
A clean trial merge does not guarantee tests pass; mergeability is a syntactic property, not a semantic one.

🔗 Related modules

📝 Quiz

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