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):

• Understand the INTENT of each change

• Determine which achieves the goal better

• Sometimes combine logic from both

• 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