Appearance
Merge Conflict Resolution: The Manual Side
When automated approaches (rerere, custom merge drivers, merge strategies) can't resolve a conflict, you have to do it by hand. This guide covers reading conflict markers, using mergetool, and the patterns that keep manual resolution fast and correct.
Why a DevOps Engineer Needs This
Automation handles the easy cases. The hard ones -- structural refactors, renamed files with semantic changes, concurrent edits to the same logic block -- land in your lap mid-merge. The difference between a 5-minute fix and a 45-minute slog is knowing what each piece of a conflict marker means, picking the right tool, and resolving in the right order.
Manual resolution is also the fallback when:
- A custom merge driver exits with code 1 (conflict)
- Rerere has no cached resolution for a new conflict signature
- The merge strategy (
-X ours/-X theirs) would silently discard the wrong side - A cherry-pick or rebase hits a conflict that bisect needs resolved
Conflict Marker Anatomy
A standard conflict looks like this with the default merge.conflictStyle = merge:
<<<<<<< HEAD
const retryCount = 3;
=======
const MAX_RETRIES = 5;
>>>>>>> feature/retry-configWith merge.conflictStyle = zdiff3 (set it -- you want this):
<<<<<<< HEAD
const retryCount = 3;
||||||| parent of abc1234 (add retry config)
const retries = 3;
=======
const MAX_RETRIES = 5;
>>>>>>> feature/retry-configThe zdiff3 format adds the common ancestor section (|||||||). This is the version both sides started from. Seeing it tells you:
- Whether one side renamed a variable while the other changed its value (semantic conflict, not just textual)
- Whether the change is additive (one side kept the base, the other modified it)
- Whether both sides made the same change to different parts of the same line
Set it globally:
git config --global merge.conflictstyle zdiff3What each section means
| Section | Label | What it is |
|---|---|---|
<<<<<<< | Ours (current branch) | The version on the branch you are merging into |
| ` | ||
======= | -- | Separator between ours and theirs |
>>>>>>> | Theirs (incoming branch) | The version from the branch you are merging from |
If the ancestor section is identical to ours or theirs, one side didn't change that region. The conflict is purely additive on the other side.
Before You Start: Quick Checks
Is it really a conflict?
Run these before you open a file:
# See which files are conflicted
git status --short | grep ^UU
# See what changed on each side for a specific file
git diff --ours conflicted-file.txt
git diff --theirs conflicted-file.txt
git diff --base conflicted-file.txtgit diff --ours shows how the ancestor became our version. git diff --theirs shows how the ancestor became their version. If one diff is empty, that side didn't touch the file.
Is it a file-level conflict?
# Unmerged paths in the index
git ls-files --unmergedThis shows the object SHAs for stage 1 (ancestor), stage 2 (ours), and stage 3 (theirs). You can extract any version:
git checkout --stage=1 -- conflicted-file.txt
git checkout --stage=3 -- conflicted-file.txtIs it a rename/delete or modify/delete conflict?
git statusThese show as DU (deleted by us, unmerged) or UD (deleted by them, unmerged). The resolution is binary: keep or delete the file. Use:
git add conflicted-file.txt # keep our version (if we deleted it, this confirms deletion)
git rm conflicted-file.txt # remove it entirely
git checkout --ours -- conflicted-file.txt # take our version
git checkout --theirs -- conflicted-file.txt # take their versionThe Mergetool Workflow
git mergetool launches a three-way diff tool that shows all three versions (ancestor, ours, theirs) plus the merge result. It's faster than editing conflict markers in a text editor.
Setup
# Pick your tool
git config --global merge.tool vimdiff
git config --global mergetool.vimdiff.layout "LOCAL,BASE,REMOTE/MERGED"
# Or VS Code
git config --global merge.tool vscode
git config --global mergetool.vscode.cmd "code --wait $MERGED"
# Or meld
git config --global merge.tool meld
# Or Beyond Compare (Windows/Linux)
git config --global merge.tool bcRun it
# Launch mergetool on all conflicted files
git mergetool
# Or a specific file
git mergetool -- conflicted-file.txtWhat each pane shows
| Pane | Label | Content |
|---|---|---|
| LOCAL | Ours | The version on your current branch |
| BASE | Ancestor | The common ancestor version |
| REMOTE | Theirs | The version from the incoming branch |
| MERGED | Result | The file that gets written on success |
In vimdiff with the layout above, LOCAL is top-left, BASE is top-center, REMOTE is top-right, and MERGED is the bottom pane. Edit the MERGED pane to produce the correct result. Save and quit. Git stages the file automatically.
After mergetool
# Verify no conflict markers remain
git diff --check
# Commit the merge
git commitIf you realise mid-resolution that you want to abort the entire merge:
git merge --abortResolution Strategies
1. Resolve by file, not by conflict
Conflicted files are independent. Fix the easy ones first (generated files, lockfiles, whitespace) and leave structural conflicts for last. The shorter the remaining list, the clearer your thinking.
# Fix the easy ones
git checkout --theirs -- package-lock.json
git checkout --ours -- .gitignore
git add package-lock.json .gitignore
# Now deal with the real conflicts
git mergetool -- src/core/parser.ts2. Take one side, then amend
For conflicts where both sides made valid changes that don't actually conflict semantically, take one side entirely, then reapply the other side's changes manually:
git checkout --theirs -- src/config.ts
# Open in editor, re-add our changes that aren't present
git add src/config.tsThis is faster than picking through markers for every chunk when one side clearly has the bulk of the correct work.
3. Split the resolution into commits
If a merge conflict spans unrelated changes (a refactor on one side, a feature addition on the other), resolve the refactor first, commit the merge, then cherry-pick the feature addition. This keeps the merge commit's diff clean and reviewable.
# During merge, resolve refactor conflicts only
git mergetool -- src/lib/core.ts
git commit -m "Merge branch 'feature/refactor' -- resolve structural conflicts"
# Now cherry-pick the feature commits from the other branch
git cherry-pick -x abc1234..def56784. Use git checkout for binary decisions
For files where you genuinely want one side's version wholesale:
git checkout --ours -- config/deploy.yaml
git add config/deploy.yamlThis avoids opening mergetool at all. Use sparingly -- if you're doing this for every conflicted file, you should have used -X ours or -X theirs at merge time.
5. Rebase vs merge conflict resolution
Merges create one resolution session for all conflicts. Rebases resolve conflicts per-commit, which means you may resolve the same conflict multiple times as each commit replays.
| Aspect | Merge | Rebase |
|---|---|---|
| Resolution session | One batch | Per commit |
| Conflict repetition | Once | Can repeat if same area touched in multiple commits |
| Rerere benefit | One entry | Multiple entries (same conflict signature) |
| Abort cost | Lose all resolution work | Lose only current commit's resolution |
For long-running branches with many commits touching the same area, merging instead of rebasing reduces total resolution time.
Advanced Patterns
Resolving in a worktree
If you're deep in another task and need to resolve a merge without touching your working tree, use a separate worktree:
git worktree add ../merge-resolution main
cd ../merge-resolution
git merge feature/conflicting-branch
# resolve conflicts here
git push origin main
cd ../original-repo
git worktree remove ../merge-resolutionUsing git diff during conflict
# See only the conflicting hunks for a file
git diff
# Compare our version to the base
git diff --ours
# Compare their version to the base
git diff --theirsThis is useful when the conflict marker is too noisy to read. You can see each side's changes independently and understand what both sides intended.
Conflict size estimation
# Count conflict markers in the working tree
grep -r "^<<<<<<< " --include="*.ts" --include="*.tsx" --include="*.py" --include="*.go" .
# Number of conflicted files
git diff --name-only --diff-filter=U | wc -lUse this in CI to decide whether a merge is safe to attempt or needs human intervention.
Common Pitfalls
Resolving with whitespace changes still in the file. Run git diff --check before staging. Trailing whitespace and space-before-tab markers that were introduced during resolution will show up as noise in the merge commit diff.
Using git commit without git mergetool or explicit git add. Git refuses to commit while conflicted files exist. git status shows UU for unmerged paths. Run git mergetool or git add on each conflicted file.
Accidentally staging a file with conflict markers still in it. Git does not prevent this. Always run git diff --check before the final commit. The merge.verbosity config option does not help here.
Resolving in the wrong direction. If you are on main merging feature/x, ours is main and theirs is feature/x. If you meant to merge main into feature/x, you should have checked out feature/x first. Use git merge --abort and switch branches.
Assuming a clean merge means a correct merge. Git merges text, not semantics. Two changes can merge without conflict markers but produce broken code (both sides added a different function with the same name, or one side renamed a function the other side started calling). Run tests after every merge.
CI Integration
Pre-merge conflict detection
# In a CI pipeline, check if a merge would produce conflicts
git merge-tree --write-tree --name-only HEAD feature/other-branch
if [ $? -ne 0 ]; then
echo "Merge would produce conflicts. Manual resolution required."
exit 1
fiThis uses git merge-tree (see the merge-tree-in-memory guide) to detect conflicts without modifying the working tree.
Automated conflict reporting
# In a post-merge CI step, report what was resolved
git log --format="%h %s" --diff-filter=M --name-only HEAD..HEAD~1This lists every file modified by the merge commit. Pair with git diff --check to flag any leftover conflict markers.
Comparison: When to use each approach
| Approach | Best for | When to skip |
|---|---|---|
| Manual marker editing | Simple single-file conflicts, small teams | Any conflict with 5+ chunks in one file |
| Mergetool (3-pane) | Complex multi-chunk conflicts, any file size | When you don't have a GUI tool installed |
--ours/--theirs | Binary files, lockfiles, generated config | Source code where both sides have valid changes |
| Custom merge driver | Machine-parseable files (lockfiles, JSON, YAML) | Source code with semantic meaning |
| Rerere | Recurring conflicts across rebases/cherry-picks | First-time conflicts |
| Merge abort + retry | Wrong base branch, wrong resolution direction | After you've already resolved 6 files |
Related Guides
- Custom Merge Drivers -- automate resolution for machine-parseable files
- Rerere -- automatic reapplication of past resolutions
- Merge Strategies -- strategy-level conflict avoidance
- Merge Tree In-Memory -- server-side conflict detection without checkout
- Cherry-Pick Conflict Recovery -- per-commit resolution in cherry-pick trains