Skip to content

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-config

With 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-config

The 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 zdiff3

What each section means ​

SectionLabelWhat 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.txt

git 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 --unmerged

This 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.txt

Is it a rename/delete or modify/delete conflict? ​

git status

These 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 version

The 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 bc

Run it ​

# Launch mergetool on all conflicted files
git mergetool

# Or a specific file
git mergetool -- conflicted-file.txt

What each pane shows ​

PaneLabelContent
LOCALOursThe version on your current branch
BASEAncestorThe common ancestor version
REMOTETheirsThe version from the incoming branch
MERGEDResultThe 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 commit

If you realise mid-resolution that you want to abort the entire merge:

git merge --abort

Resolution 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.ts

2. 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.ts

This 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..def5678

4. 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.yaml

This 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.

AspectMergeRebase
Resolution sessionOne batchPer commit
Conflict repetitionOnceCan repeat if same area touched in multiple commits
Rerere benefitOne entryMultiple entries (same conflict signature)
Abort costLose all resolution workLose 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-resolution

Using 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 --theirs

This 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 -l

Use 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
fi

This 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~1

This 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 ​

ApproachBest forWhen to skip
Manual marker editingSimple single-file conflicts, small teamsAny conflict with 5+ chunks in one file
Mergetool (3-pane)Complex multi-chunk conflicts, any file sizeWhen you don't have a GUI tool installed
--ours/--theirsBinary files, lockfiles, generated configSource code where both sides have valid changes
Custom merge driverMachine-parseable files (lockfiles, JSON, YAML)Source code with semantic meaning
RerereRecurring conflicts across rebases/cherry-picksFirst-time conflicts
Merge abort + retryWrong base branch, wrong resolution directionAfter you've already resolved 6 files

Git Master — Git Reference for Every Skill Level