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

Pattern 1: Sequential Changes

<<<<<<< HEAD
function processUser(user) {
  validateUser(user);
=======
function processUser(user) {
  logUserAccess(user);
>>>>>>> feature-branch

Resolution: Keep both - they're independent additions

function processUser(user) {
  validateUser(user);
  logUserAccess(user);

Pattern 2: Competing Implementations

<<<<<<< HEAD
const result = items.filter(x => x.active).map(x => x.name);
=======
const result = items.reduce((acc, x) => x.active ? [...acc, x.name] : acc, []);
>>>>>>> feature-branch

Resolution: Choose based on readability/performance needs. The filter().map() is clearer.

Pattern 3: Configuration Changes

<<<<<<< HEAD
const API_URL = 'https://api.prod.example.com';
=======
const API_URL = 'https://api.staging.example.com';
>>>>>>> feature-branch

Resolution: This is environment-specific. Use environment variables instead:

const API_URL = process.env.API_URL || 'https://api.prod.example.com';

Tools

# Use a merge tool (if configured)
git mergetool

# Abort if things go wrong
git merge --abort
git rebase --abort

# Accept all of one side (use carefully)
git checkout --ours <file>    # Keep your version
git checkout --theirs <file>  # Keep their version

Common Mistakes to Avoid

• Never blindly accept "ours" or "theirs" without understanding the changes
• Don't leave conflict markers in code (<<<<<<, =======, >>>>>>>)
• Don't skip running tests after resolution
• Don't force push to shared branches after rebase conflicts
• Don't ignore whitespace or formatting conflicts - they can hide real issues

Emergency Recovery

# If you messed up the resolution
git checkout -m <file>  # Restore conflict markers

# If you committed a bad resolution
git reset --soft HEAD~1  # Undo commit, keep changes
# Then resolve again

# Nuclear option: start over
git merge --abort  # or git rebase --abort