Merge Algorithms, Conflict Engineering, rerere, and Custom Merge Drivers: Concepts, Architecture, and Mental Model

1. A merge conflict is an integration decision, not a marker-removal exercise

Earlier chapters established the commit graph, merge bases, index stages, refs, attributes, hooks, and low-level state. This chapter combines those ideas into a systematic merge workflow. Git can compute a candidate integration, but it cannot know every business invariant, API contract, generated-file rule, or deployment assumption. Therefore a merge is complete only when repository state is resolved and the integrated behavior is validated.

2. Inspect topology and configuration before mutating state

git --version
git status --short --branch
git log --graph --decorate --oneline --all --max-count=40
git merge-base --all HEAD topic
git config --list --show-origin --show-scope
git check-attr merge text eol -- path/to/file

These commands establish the Git version, clean/dirty state, branch topology, candidate bases, configuration origins, and path attributes. Record them before unusual integrations because strategy behavior and driver configuration can be version- or environment-sensitive.

3. A true merge reasons from base, ours, and theirs

flowchart LR
B[Merge base]
B --> O[Ours: HEAD]
B --> T[Theirs: topic]
O --> R[Integrated result]
T --> R
B -. comparison reference .-> R

Git compares changes from the merge base to each tip. “Ours” is the current HEAD side during an ordinary merge; “theirs” is the side being merged. The base provides the common context needed to decide whether a change was made on one side, both sides, or neither.

4. Multiple merge bases can require a virtual base

Criss-cross histories can have more than one best common ancestor. Current ort merge machinery consolidates multiple bases recursively into a virtual base before the final three-way merge. Therefore a home-grown tool that chooses an arbitrary first merge base can produce different results from Git.

git merge-base --all left right

5. Current Git uses ort as the default strategy for merging one branch

Current Git 2.55 documentation defines ort as the default two-head strategy. It performs three-way content merging, handles renames, and consolidates multiple common ancestors. Strategy names are version-sensitive: beginning with Git 2.50.0, recursive is redirected to mean ort; older Git releases can still use the previous recursive implementation.

6. -Xours and -s ours are fundamentally different

7. Conflict families extend beyond text markers

A content conflict is an unresolved file-level three-way merge. Structural conflicts include rename/delete, rename/rename, file/directory, mode, and binary conflicts. These can produce status/index evidence without familiar text markers. Therefore “grep for <<<<<<<” is not a valid merge-completeness check.

8. The index preserves the three conflicting inputs

When a normal merge stops, the index can contain stage 1 (base), stage 2 (ours/HEAD), and stage 3 (theirs/MERGE_HEAD) for an unresolved path.

git ls-files -u
git show :1:path/to/file
git show :2:path/to/file
git show :3:path/to/file

Current ort also writes AUTO_MERGE, a tree representing the working-tree merge result, including textual conflict markers where applicable. HEAD itself remains at the pre-merge commit until the merge is committed.

9. Semantic conflicts can merge cleanly

Imagine a configuration where one branch raises a minimum capacity and another lowers a maximum capacity in well-separated lines. Git can combine both textual edits without markers while the resulting minimum > maximum violates a business invariant. Only domain tests or review can detect that failure.

10. git merge-tree --write-tree previews merge machinery without touching live index/worktree state

git merge-tree --write-tree trunk topic
echo "exit=$?"

Modern merge-tree uses the same important merge features as real merging, including rename detection and file/directory conflict handling. It does not make a merge commit or update the live index/worktree. Exit 0 means clean; exit 1 means conflicts. On conflict, stdout contains conflict information in addition to a top-level tree OID, so scripts must inspect exit status and documented output structure.

11. rerere reuses a previously recorded conflict resolution

rerere means “reuse recorded resolution.” With rerere.enabled, Git records a conflicted preimage and the resolution you later stage/record. When an equivalent conflict appears again, Git can apply the remembered result. That saves repetitive editing but does not prove the old decision remains correct.

12. Reuse and automatic staging are separate policy choices

With rerere.autoUpdate=false, rerere can update the working-tree file while leaving the index unmerged. That gives reviewers a chance to inspect and test the reuse before git add. With autoupdate enabled, Git may stage the reused resolution automatically, which is faster but removes that explicit checkpoint.

13. Attributes select a merge driver; configuration defines the executable command

generated/components.lock merge=generatedComponents

[merge "generatedComponents"]
    name = deterministic generated-component merger
    driver = trusted-generated-merge %O %A %B %L %P

The driver receives temporary base/ours/theirs files. It must write a clean result to %A and return zero only when the result is valid. The tracked attribute can travel to another clone; the trusted executable configuration/runtime usually does not.

14. Custom merge drivers are a trust and portability boundary

A custom driver is executable code invoked by Git during an integration-sensitive operation. Provision it explicitly, review it, quote arguments safely, fail non-zero on ambiguous input, and ensure CI uses a compatible runtime. A repository naming a driver does not mean every machine should trust and execute an arbitrary command.

15. DevOps connection — merge reliability is a quality gate

A production integration should answer four questions independently: did Git compute a mechanical result, are all index conflicts resolved, do domain tests validate the combined behavior, and did any exceptional automation such as rerere, strategy options, or custom drivers make a decision that deserves extra scrutiny? A marker-free merge can still be a failed delivery candidate.

16. Knowledge check

17. Summary

Merge engineering begins with topology and current strategy behavior, preserves base/ours/theirs evidence in the index, distinguishes structural from semantic conflicts, and treats rerere/drivers as automation that must remain reviewable and testable.

Authoritative references

• git-merge
• merge-strategies
• git-merge-tree
• git-rerere
• gitattributes