Resolve merge conflicts file-by-file. Use when a merge/rebase has conflicts, a PR can't merge, "fix conflicts" is requested, or branches have diverged.
Resolve merge conflicts file-by-file. Use when a merge/rebase has conflicts, a PR can't merge, "fix conflicts" is requested, or branches have diverged.
This gives three-way conflict markers with the common ancestor, compacted by removing shared lines at conflict boundaries. Much easier to resolve than the default two-way markers.
Step 3: Resolve conflicts
If --ours flag: Accept current branch for all conflicted files:
git restore --ours -- <file> # for each file
git add <file>
If --theirs flag: Accept incoming branch for all conflicted files:
git restore --theirs -- <file> # for each file
git add <file>
Otherwise, resolve each file intelligently:
For each file from git diff --name-only --diff-filter=U:
Read the file — with zdiff3, conflict markers look like:
<<<<<<< HEAD
(current branch changes)
||||||| (common ancestor)
(what the code looked like before both changes)
=======
(incoming changes)
>>>>>>> branch-name
The ||||||| section (common ancestor) shows what both sides started from — use it to understand intent
Apply resolution strategy by file type:
File Type
Strategy
package.json, plugin.json
Merge objects/arrays, take higher versions
YAML config
Merge keys from both sides
CHANGELOG.md
Include entries from both sides in chronological order
README.md, docs
Include content from both sides
Source code
Integrate both changes preserving logic of each
Lock files (bun.lock, package-lock.json)
Delete and regenerate after resolving other files
.release-please-manifest.json
Take higher version numbers
Edit the file to remove ALL conflict markers (<<<<<<<, |||||||, =======, >>>>>>>) and combine changes
Stage: git add <file>
Important ours/theirs note for rebases: During git rebase, the meaning of ours/theirs is swapped — --ours refers to the branch being rebased onto (usually main), --theirs refers to your feature branch commits.
Step 4: Verify and complete
Check no conflict markers remain: search all resolved files for <<<<<<<
Check if rerere recorded anything: git rerere status
Complete the operation:
If merging: git commit --no-edit
If rebasing: git rebase --continue
If --push flag: git push origin $(git branch --show-current)
Step 5: Report results
Summarize what was resolved:
List each file and how it was resolved (merged both sides, accepted ours/theirs, regenerated)
Note if rerere recorded new resolutions for future reuse
If PR number was provided (or detected from branch), comment on the PR:
gh pr comment <number> --body "Merge conflicts with <base-branch> resolved automatically.
Resolved files:
- file1.json (merged entries from both sides)
- file2.md (combined changelog entries)
"
Conflict Resolution Patterns
JSON Files
Merge array entries from both sides, deduplicate
For version fields, take the higher version
For object properties, include properties from both sides
Validate JSON after resolution
Markdown Files
Include content from both sides
Maintain chronological order for changelogs
Include table rows from both sides
Source Code
Use the common ancestor (zdiff3 ||||||| section) to understand what both sides changed
Integrate both modifications preserving the intent of each
If same line changed incompatibly, prefer the PR branch change and note in commit message
Squash Merge Pitfall
If the same conflicts keep recurring, the likely cause is squash merges. Squash-merging breaks the common ancestry chain, so stacked or sibling branches lose their merge base. Rerere mitigates this by replaying recorded resolutions, but the root fix is to avoid squash merges on branches with dependents. When a squashed base leaves a dependent carrying the now-collapsed commits, recover with git rebase --onto origin/main <old-base-tip> <dependent> (see the git-pr skill's Stacked PRs section).
When to Abort
Abort with git merge --abort or git rebase --abort if:
Conflicts span many files with incompatible architectural changes
Resolution requires understanding business requirements you don't have context for
Lock files are the only conflicts (delete, regenerate, commit)
Pre-Merge Trial Integration (landing a wave of PRs)
When several branches will land together — a wave of parallel feature branches,
a PR stack, or sibling fixes touching overlapping files — surface and resolve
the conflicts once, on a throwaway branch, before touching main. This also
catches the silent failure a plain auto-merge can't: when two branches each add
the same helper/import in non-adjacent spots, git merges both copies with no
conflict, producing a tree that does not compile. The merge message is not
proof of correctness — only compiling the merged tree is.
# rerere on, so the resolution you do here is recorded for the real merges
git config rerere.enabled true
git config rerere.autoupdate true
git switch -c trial/integration origin/main
for b in <branch-1> <branch-2> <branch-3>; do
git merge --no-ff --no-edit "origin/$b" || git commit --no-edit # resolve, then commitdone
<build + testcommand> # e.g. just check / cargo test / npm test — the real gate
If the merged tree builds and tests green, the resolution is validated and
rerere has cached it. Discard the trial branch and do the real merges/rebases
in order — rerere auto-replays the same resolution on the actual base merge and
on each dependent's --onto rebase (see git-pr Stacked PRs), so you never
re-resolve by hand:
git switch main && git branch -D trial/integration # the rerere cache persists
Payoff: conflicts surface before main is touched (not mid-merge under
pressure); one resolution is replayed everywhere via rerere; and compiling the
merged tree catches silent duplicate-addition merges a green merge message hides.
Quick Reference
Task
Command
List conflicted files
git diff --name-only --diff-filter=U
Re-checkout with zdiff3
git checkout --conflict=zdiff3 -- <file>
Accept current branch
git restore --ours -- <file>
Accept incoming branch
git restore --theirs -- <file>
Recreate conflict markers
git checkout -m -- <file>
Check rerere status
git rerere status
View rerere diff
git rerere diff
Forget bad resolution
git rerere forget <file>
Abort merge
git merge --abort
Abort rebase
git rebase --abort
Continue rebase
git rebase --continue
Agentic Optimizations
Context
Command
List conflicts
git diff --name-only --diff-filter=U
Conflict count
git diff --name-only --diff-filter=U | wc -l
Full conflict diff
git diff --diff-filter=U
PR mergeable state
gh pr view N --json mergeable
Check markers remain
grep -rn '<<<<<<<' <files>
Porcelain status
git status --porcelain=v2
Detect merge/rebase state
test -f .git/MERGE_HEAD && echo merge || test -d .git/rebase-merge && echo rebase
