git-conflicts

/git:conflicts

Resolve merge conflicts using modern git features.

When to Use This Skill

Use this skill when...	Use git-ops agent instead when...
Merge or rebase produced conflicts	Complex multi-branch cherry-pick across many commits
PR shows "can't merge" / "fix conflicts"	Conflicts require deep business logic understanding
Config files (JSON, YAML, lockfiles) diverged	Interactive rebase with squash/fixup needed
Need to accept one side wholesale (--ours/--theirs)	Architectural redesign spanning many files

Context

• Current branch: !git branch --show-current
• Git status: !git status --porcelain=v2 --branch
• Merge state: !find .git -maxdepth 1 -name 'MERGE_HEAD' -o -name 'REBASE_HEAD' -o -name 'rebase-merge' -o -name 'rebase-apply'
• Conflicted files: !git diff --name-only --diff-filter=U
• Conflict style: !git config --default '' merge.conflictStyle
• Rerere enabled: !git config --default '' rerere.enabled
• Git version: !git version

Parameters

Parse these from $ARGUMENTS:

• $1: File path (resolve single file) OR PR number (fetch and merge base branch)
• --ours: Accept current branch version for all conflicts
• --theirs: Accept incoming branch version for all conflicts
• --push: Push after resolution is committed

Execution

Execute this conflict resolution workflow:

Step 1: Assess the situation

1. Check context for existing merge/rebase state (MERGE_HEAD, REBASE_HEAD, rebase-merge, rebase-apply)
2. If PR number provided and no active merge state:
   • Get PR details: gh pr view <number> --json headRefName,baseRefName,mergeable
   • Fetch base: git fetch origin <base-branch>
   • Pick the sync method:
     • Default — rebase: git rebase origin/<base-branch>. A merge commit in a PR branch forces the PR to squash-merge (rule 4 in github-pr-title → merge-strategies.md), so rebasing keeps the PR rebase-eligible.
     • Fallback — merge: git merge origin/<base-branch> --no-ff when the branch is shared (someone else has commits on it, or another PR is based on it) or a rebase is not allowed to force-push.
   • If the sync succeeds cleanly, report "No conflicts" and exit
3. If no PR number and no active merge state, detect from current branch:
   • gh pr list --head $(git branch --show-current) --json number,baseRefName,mergeable
   • Use the detected PR number and base branch; proceed as above
4. List conflicted files: git diff --name-only --diff-filter=U
5. If no conflicted files found, report current status and exit

Step 2: Configure zdiff3 (if not set)

Check the conflict style from context. If merge.conflictStyle is not zdiff3:

1. Set for this repo: git config merge.conflictStyle zdiff3
2. Re-checkout conflicted files with zdiff3 markers: git checkout --conflict=zdiff3 -- <file> for each conflicted file
3. Enable rerere if not already: git config rerere.enabled true
4. Enable rerere autoupdate: git config rerere.autoupdate true (auto-stages files resolved by rerere)

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:

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

2. The ||||||| section (common ancestor) shows what both sides started from — use it to understand intent
3. 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

4. Edit the file to remove ALL conflict markers (<<<<<<<, |||||||, =======, >>>>>>>) and combine changes
5. 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

1. Check no conflict markers remain: search all resolved files for <<<<<<<
2. Check git diff --name-only --diff-filter=U returns empty (no remaining unmerged paths)
3. Check if rerere recorded anything: git rerere status
4. Complete the operation:
   • If merging: git commit --no-edit
   • If rebasing: git rebase --continue; a rebase stops once per conflicting commit, so repeat Steps 3–4 until it finishes
5. If --push flag: git push origin $(git branch --show-current) after a merge, or git push --force-with-lease origin $(git branch --show-current) after a rebase

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: Example gh pr comment body: REFERENCE.md.

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

Same conflicts recurring after squash merges: cause, rerere mitigation and --onto recovery in REFERENCE.md.

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, resolve their conflicts once on a throwaway trial branch with rerere on, and build and test that merged tree before touching main. Recipe: REFERENCE.md.

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