merge-conflict-surgeon

Merge Conflict Surgeon

Resolve Git merge conflicts systematically and safely.

When to Use

• git merge or git rebase fails with conflicts
• You see conflict markers (<<<<<<<, =======, >>>>>>>) in files
• git status shows "both modified" files
• Merging feature branches into main/develop
• Rebasing a branch onto updated main

Workflow

Step 1: Assess the Damage

# See all conflicted files
git status

# See the full diff of conflicts
git diff --name-only --diff-filter=U

List all conflicted files and categorize them:

• Simple conflicts: Same file, different lines (auto-resolvable logic)
• Overlap conflicts: Same lines modified differently (needs human decision)
• Delete/modify conflicts: One side deleted, other modified

Step 2: Understand Both Sides

For each conflicted file, understand:

# See what YOUR branch changed
git diff HEAD~1 -- <file>

# See what the OTHER branch changed
git diff MERGE_HEAD~1 -- <file>

# See common ancestor
git show :1:<file>  # Base version
git show :2:<file>  # Ours (current branch)
git show :3:<file>  # Theirs (merging branch)

Step 3: Resolve Strategically

For simple conflicts (different functionality):

• Keep both changes, ensure they don't break each other
• Run the code mentally or actually to verify

For overlapping conflicts (same code, different changes):

1. Understand the INTENT of each change
2. Determine which achieves the goal better
3. Sometimes combine logic from both
4. Never blindly pick "ours" or "theirs"

For delete/modify conflicts:

• If deleted intentionally (refactoring), ensure the modification isn't needed
• If deleted accidentally, restore and apply modification

Step 4: Validate Resolution

# Mark as resolved
git add <resolved-file>

# Verify no remaining conflicts
git diff --check

# Run tests before completing
npm test  # or your test command

# Complete the merge
git commit  # or git rebase --continue

Resolution Patterns