Git Merge Conflict — --theirs Wiped a Security Header

Every team that uses Git will eventually hit a merge conflict. It is not a sign something went wrong — it is a sign your team is working in parallel, which is exactly what Git is built for. The problem is that most developers treat conflicts like a fire alarm: panic, smash the keyboard, accept every incoming change, and hope for the best. That approach silently breaks production code and ruins trust in your codebase.

Merge conflicts exist because Git tracks changes at the line level. When two branches modify the same line (or adjacent lines) independently, Git cannot apply both changes automatically without risking data loss. So it stops, marks the battlefield inside the file, and waits for you. The conflict markers Git leaves behind are not cryptic error messages — they are a structured diff you can read and act on deliberately.

By the end of this article you will be able to: read and interpret conflict markers without guessing, manually resolve conflicts with confidence, use a three-way merge tool to handle complex conflicts visually, abort or retry a merge cleanly when things go sideways, and adopt the team habits that prevent unnecessary conflicts in the first place.

Why Git Merge Conflicts Happen — and When to Expect Them

Git merges work beautifully most of the time because the changes on two branches touch different files or different sections of the same file. Git's merge algorithm is smart enough to combine those non-overlapping edits automatically. Conflicts only surface when the algorithm genuinely cannot make a safe decision.

There are three common triggers. First, two developers edit the exact same line in the same file on different branches. Second, one developer edits a block of code while another deletes that entire file. Third, two developers rename the same file to different names. Each of these cases forces Git to stop and defer to a human.

The branch strategy your team uses matters enormously here. Long-lived feature branches that drift far from main are conflict factories — by the time you merge, dozens of lines may have diverged. Short-lived branches merged frequently are the antidote. Knowing this changes how you plan your work, not just how you fix conflicts after they happen.

Conflicts during a rebase feel slightly different from conflicts during a merge because a rebase replays commits one at a time, so you might resolve the same conceptual conflict multiple times. Understanding which operation triggered the conflict changes how you resolve it.

#!/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

Reading Conflict Markers — Decoding What Git Actually Wrote in Your File

After a conflict, Git edits the file directly and inserts markers to show you both sides of the disagreement. Most developers scan these markers, pick a side, and move on. That works for trivial conflicts. For anything real, you need to read all three pieces of information Git gives you.

The structure is always the same. The <<<<<<< HEAD line opens the block and the content below it is what YOUR current branch has. The ======= line is the divider. Everything below the divider down to >>>>>>> feature/branch-name is what the incoming branch contributed. Between those three markers is the full picture of the disagreement.

What most guides skip is the base — the version that BOTH branches started from before they diverged. Git stores this internally. Knowing the base tells you whether both developers added new logic (in which case you likely need to keep both), or whether they both rewrote the same existing logic (in which case you need to pick the right one). Without the base, you are reading a debate without knowing what both parties agreed on before it started.

You can surface the base yourself with git diff --diff-filter=U or by configuring Git to use the diff3 conflict style, which embeds the ancestor version directly between the markers. This single setting prevents enormous amounts of bad conflict resolution.

#!/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

Resolving Conflicts Three Ways — Manual Edit, git mergetool, and Theirs/Ours

There is no single correct way to resolve a conflict — the right approach depends on how complex the conflict is and what the code is doing. You have three practical options and each has a place.

Manual editing works well for simple conflicts: open the file, delete the markers, keep the correct code, save. This forces you to read the code carefully, which is often exactly what you should do. It breaks down when conflicts span dozens of lines or when you cannot tell which version is correct without seeing both in context side-by-side.

A three-way merge tool (like VS Code, IntelliJ, or vimdiff) shows you the base, the current branch, and the incoming branch in three panes simultaneously, with a fourth result pane you build from clicking to accept each hunk. This is the right approach for complex conflicts involving multiple changed functions.

The --ours and --theirs flags are a power tool for a specific situation: when you know categorically that one entire side is correct. They are NOT a shortcut for laziness. Use --ours to keep the current branch's version of a file in full, and --theirs to take the incoming branch's full version. Misusing these flags is one of the most common ways teams silently discard real code changes.

After any resolution method, the workflow is identical: stage the file, verify the state, and commit.

#!/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.

Aborting, Retrying, and Preventing Conflicts Before They Happen

Sometimes mid-conflict you realize the merge itself is wrong — the wrong branches were targeted, or you need to pull in new commits before continuing. Git gives you a clean escape hatch: git merge --abort. This rewinds everything back to exactly where you were before you ran the merge. No damage done.

For rebases the equivalent is git rebase --abort. And if you are mid-cherry-pick, git cherry-pick --abort does the same. Always abort cleanly rather than trying to manually reset files — the abort commands guarantee a clean working tree.

Retryin a merge after aborting is as simple as re-running the original merge command, ideally after fetching new changes or after your teammates have confirmed the affected code.

Prevention is worth ten resolutions. The habits that eliminate most conflicts are: merge or rebase from main frequently (at least daily on active branches), keep feature branches short-lived and narrowly scoped, split large files into smaller modules so fewer developers edit the same file, and communicate before refactoring shared utilities. Code ownership boundaries in large teams reduce conflict rates dramatically because they reduce the probability that two people edit the same lines at the same time.

#!/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

Post-Merge Verification — Ensuring the Merge Didn't Break Anything

The merge is committed, but you're not done yet. A surprising number of bugs originate from conflict resolutions that looked right but silently broke logic. You need a verification checklist that goes beyond 'it compiles'.

First, diff the merge commit against its first parent: git diff HEAD~1 — this shows every change that came into your branch because of the merge. Look especially at files that were conflicted. If the diff shows lines you didn't expect, you might have chosen the wrong hunk.

Second, run the test suite. But don't stop at green — check the test coverage on the conflicted files. If those files have no tests, that's a red flag. Add a test that exercises the merged code path.

Third, use git log --first-parent to see the merge commit as a single unit. This is especially important in code review — reviewers should not have to dig through the full merge diff if you've already verified it.

Finally, if the merge touched configuration or infrastructure files, run a validation script that checks for required keys or settings. Automate this in CI so no merge goes to production without passing config validation.

#!/usr/bin/env bash
# -----------------------------------------------------------
# POST-MERGE VERIFICATION CHECKLIST
# Run these steps after every merge, especially complex ones.
# -----------------------------------------------------------

# 1. Show the full diff of what the merge brought in
echo "=== Full merge diff ==="
git diff HEAD~1

# 2. List only the files that were conflicted and resolved
echo "=== Files that had conflicts ==="
git log --oneline --name-only -1 --diff-filter=M | head -20

# 3. Check for accidental marker leftovers in the entire repo
echo "=== Marker scan ==="
grep -r '<<<<<<<\|=======\|>>>>>>>' --include='*.py' --include='*.js' --include='*.ts' --include='*.yaml' --include='*.json' . && echo "WARNING: markers found!" || echo "Clean — no markers"

# 4. Run tests, focusing on affected modules
# pytest tests/ -k "sauce or config"  (example for specific modules)

# 5. If config files changed, validate required keys
# python validate_config.py

Using Git Merge Tools for Complex Conflicts — VS Code, IntelliJ, and vimdiff

Manual editing works for simple conflicts, but when a file has multiple conflict regions across several functions, a three-way merge tool saves time and reduces errors. These tools show three versions simultaneously: the base (common ancestor), the current branch, and the incoming branch. You build the result by picking hunks from either side or editing directly.

VS Code has a built-in three-way merge editor that activates when you open a conflicted file. It shows four panes: base, current, incoming, and result. You can click buttons to accept current, accept incoming, or accept both. IntelliJ IDEA's merge tool works similarly with a cleaner diff view.

Vimdiff is the terminal-based fallback. It splits the terminal into vertical panes. It takes some practice but is invaluable when you're SSH'd into a server or working without a GUI.

To launch a merge tool during a conflict, run git mergetool. Git will automatically open the configured tool for each conflicted file. Configure your preferred tool once: git config --global merge.tool vscode (or intellij, vimdiff, etc.). Some tools need additional command configuration — check the documentation.

The biggest advantage of a merge tool is that you see all three versions at once. You can spot when both branches added different lines near the same region, or when one branch deleted something the other kept. Visual comparison reduces blind mispicks.

#!/usr/bin/env bash
# -----------------------------------------------------------
# CONFIGURE AND USE MERGE TOOLS
# -----------------------------------------------------------

# Set VS Code as the default merge tool (one-time)
git config --global merge.tool vscode
git config --global mergetool.vscode.cmd 'code --wait $MERGED'

# Set IntelliJ as the default
git config --global merge.tool intellij
git config --global mergetool.intellij.cmd 'idea merge $LOCAL $REMOTE $BASE $MERGED'

# Set vimdiff as the default (built-in, no extra config)
git config --global merge.tool vimdiff

# Launch the merge tool during a conflict
git mergetool

# If you want to skip a file, use --no-prompt or abort mid-tool
# To see allowed tools: git mergetool --tool-help

# After resolving with the tool, the result is automatically staged
# Just commit: git commit