Resolving Git Merge Conflicts: A Practical Guide for Developers

#!/usr/bin/env bash
# -----------------------------------------------------------
# Demonstration: deliberately create a merge conflict so you
# can see exactly what Git reports and what it writes into
# the conflicted file.
# -----------------------------------------------------------

# 1. Create a fresh repo so this is fully self-contained
mkdir recipe-api && cd recipe-api
git init
git config user.email "demo@thecodeforge.io"
git config user.name "CodeForge Demo"

# 2. Add a shared starting file on main (the "common ancestor")
cat > sauce.py << 'EOF'
def get_sauce():
    return "tomato"
EOF

git add sauce.py
git commit -m "chore: initial sauce implementation"

# 3. Branch A: the backend dev changes the sauce to 'arrabiata'
git checkout -b feature/arrabiata-sauce
sed -i 's/tomato/arrabiata/' sauce.py   # edit the same line
git add sauce.py
git commit -m "feat: switch sauce to arrabiata"

# 4. Back on main: a second dev changes the sauce to 'marinara'
git checkout main
sed -i 's/tomato/marinara/' sauce.py   # edit the SAME line differently
git add sauce.py
git commit -m "feat: switch sauce to marinara"

# 5. Attempt to merge — this is where Git raises its hand
git merge feature/arrabiata-sauce

#!/usr/bin/env bash
# -----------------------------------------------------------
# Part 1: Enable diff3 style BEFORE you merge — this adds the
# common ancestor (base) into the conflict block so you have
# full context. Set it globally so every future conflict is clearer.
# -----------------------------------------------------------

git config --global merge.conflictStyle diff3

# -----------------------------------------------------------
# Part 2: After running the conflict from the previous section,
# cat the file to see all three layers Git embedded.
# -----------------------------------------------------------

cat sauce.py

# -----------------------------------------------------------
# Part 3: The output below shows what diff3 style looks like.
# Read it from top to bottom:
#
#   <<<<<<< HEAD            <- your branch starts here
#     return "marinara"     <- what YOUR branch says
#   ||||||| merged common ancestors  <- BASE (what BOTH branches started from)
#     return "tomato"       <- the original value before anyone changed it
#   =======                 <- incoming branch starts here
#     return "arrabiata"    <- what the INCOMING branch says
#   >>>>>>> feature/arrabiata-sauce
#
# Decision logic:
#   - Both changed "tomato" to something different => editorial conflict, pick one
#   - One added new lines, other didn't change them => keep both
#   - Base is already gone on both sides => both deleted, no conflict needed
# -----------------------------------------------------------

# Part 4: List ALL conflicted files in a repo (useful in large merges)
git diff --name-only --diff-filter=U

# Part 5: See a detailed diff of just the conflicted regions
git diff

#!/usr/bin/env bash
# -----------------------------------------------------------
# METHOD 1: Manual edit
# Open the file in your editor, remove the markers, keep the
# correct content, then stage and commit.
# -----------------------------------------------------------

# Manually edit sauce.py to contain only the correct content:
cat > sauce.py << 'EOF'
def get_sauce():
    # Product decision: use arrabiata for the spicy menu launch
    return "arrabiata"
EOF

# Confirm no conflict markers remain (grep returns nothing = good)
grep -n '<<<<<<<\|=======\|>>>>>>>' sauce.py \
    && echo "WARNING: markers still present" \
    || echo "Clean — no conflict markers found"

# Stage the resolved file
git add sauce.py

# Confirm Git sees it as resolved (no 'UU' entries should remain)
git status

# Commit the merge
git commit -m "fix: resolve sauce conflict — use arrabiata for spicy launch"


# -----------------------------------------------------------
# METHOD 2: Configure VS Code as your merge tool, then launch it
# Run these once to set it up globally:
# -----------------------------------------------------------

git config --global merge.tool vscode
git config --global mergetool.vscode.cmd 'code --wait $MERGED'

# Then during a conflict, run:
# git mergetool
# VS Code opens with the three-way merge editor. Accept hunks
# using the UI buttons. Save and close. Git marks it resolved.


# -----------------------------------------------------------
# METHOD 3: Accept one full side (use carefully and deliberately)
# --ours  = keep the current branch's entire file
# --theirs = take the incoming branch's entire file
# -----------------------------------------------------------

# Scenario: The incoming branch has a regenerated lock file
# (e.g. package-lock.json) and you always want to take the
# incoming version because it was built from the correct
# dependency tree.
git checkout --theirs package-lock.json
git add package-lock.json
# Then commit as normal.

# IMPORTANT: --ours/--theirs operates on WHOLE FILES.
# There is no partial --theirs. If you need to mix lines
# from both sides, you must use method 1 or 2.

#!/usr/bin/env bash
# -----------------------------------------------------------
# ABORTING: clean escape from a merge gone wrong
# -----------------------------------------------------------

# You are mid-merge and realize the branch targets are wrong
git merge --abort
# Git prints nothing on success — run git status to confirm:
git status
# Expected: "nothing to commit, working tree clean"

# Same pattern for rebase and cherry-pick:
# git rebase --abort
# git cherry-pick --abort


# -----------------------------------------------------------
# PREVENTION PATTERN 1: Sync your feature branch with main daily
# This is the single most effective conflict-prevention habit.
# -----------------------------------------------------------

git checkout feature/payment-refactor

# Option A — Merge main into your branch (preserves history, safer for shared branches)
git fetch origin
git merge origin/main
# If there are conflicts here, they are small because you synced recently.
# Resolve them, then continue your work.

# Option B — Rebase onto main (linear history, better for solo feature branches)
git fetch origin
git rebase origin/main
# Rebase replays YOUR commits on top of the latest main.
# Each commit is replayed individually, so resolve conflicts per-commit if needed.
git rebase --continue   # run this after resolving each commit's conflicts


# -----------------------------------------------------------
# PREVENTION PATTERN 2: Check what a merge WOULD conflict on
# before actually running it (dry-run style inspection)
# -----------------------------------------------------------

# Find files changed on both branches since they diverged:
git fetch origin
MERGE_BASE=$(git merge-base HEAD origin/main)   # find the common ancestor commit
echo "Common ancestor: $MERGE_BASE"

# Files your branch touched:
git diff --name-only "$MERGE_BASE" HEAD

# Files main touched since that ancestor:
git diff --name-only "$MERGE_BASE" origin/main

# The overlap between these two lists = your likely conflict zones
# Review those files with your teammate BEFORE merging