merge-conflict-resolution — resolve blocks, never replace files

Overview

A merge conflict file has THREE kinds of content: conflict blocks (both sides shown), auto-merged lines git already combined for you, and untouched context. Every data-loss incident in this class comes from treating the file as two-kinds: a resolver that replaces the whole file, or a script that eats the lines between blocks.

Core rule: resolve conflict BLOCKS. Anything that replaces the FILE destroys auto-merged work — silently, with a clean git status.

The trap that passes every naive check

git checkout --theirs <file> does NOT mean "take their side of the conflicts". It replaces the whole file with their version — every line the other side added outside the conflicts is gone. Then:

• git status — clean ✓ (loss is staged, status can't see it)
• git diff --check — no markers ✓
• git log --graph — proper merge commit, two parents ✓

All green, data lost. This exact sequence shipped a deleted "critical security notice" line in a 17-second baseline test, and lost README lines twice in production.

Doing it right

Script rules (if you automate block editing):

• Process line-by-line with a state machine (<<<<<<< opens, >>>>>>> closes). Never a regex spanning from <<<<<<< to >>>>>>> — greedy or multiline matching eats everything between two blocks. This is the production bug this skill exists for.
• Fail fast on anything unmapped (unknown section, nested markers) — crash beats guess.
• Keep the pre-resolution file: cp file file.conflicted before touching it.

Verify before commit — three checks, all mandatory

# 1. No markers anywhere in the repo (not just the file you edited)
git -C "$R" diff --check && git -C "$R" grep -nE '^(<<<<<<<|=======|>>>>>>>)' -- . ; # grep must find nothing

# 2. NO LINE OUTSIDE CONFLICT BLOCKS WAS LOST — the check that catches --theirs and greedy regex
awk '/^<<<<<<</{c=1} /^>>>>>>>/{c=0;next} !c' file.conflicted > /tmp/outside
grep -Fxvf <resolved-file> /tmp/outside   # must print NOTHING; every printed line was eaten
# (file.conflicted is the copy you kept; recover one with `git checkout -m <file>` if you didn't)

# 3. Each block resolved to the INTENDED side — grep the distinctive line of each choice

Only after all three: git add + commit. If you resolved during a review/приёмка of someone else's merge — run the same three checks on their result; a clean status is not evidence.

Acceptance merges — merging someone's finished branch

Same discipline, different trap: here nothing conflicts, so nothing feels dangerous. Two real incidents in one:

Pre-flight (before any merge command):

git -C "$R" status --short          # whose tree is this? CLEAN? In multi-agent setups the
                                    # checkout may belong to a LIVE agent mid-task — uncommitted
                                    # files here mean STOP, not stash.
git -C "$R" branch --show-current   # you merge INTO where HEAD points. If it's not the target
                                    # branch, checkout first — a merge "into main" executed on
                                    # someone's work-branch lands there silently and looks fine.

Post-push (after any push):

git -C "$R" ls-remote origin <target-branch>   # compare to local SHA yourself

The push command's own output is not evidence: Everything up-to-date prints on a no-op push (wrong branch pushed = nothing rejected, nothing transferred, success-looking output, remote unchanged). Report the ls-remote SHA, not the push output.

Rationalizations — heard in real incidents

Red flags — STOP

• Typing checkout --ours/--theirs on a text file while auto-merged changes exist
• A conflict-parsing regex with [\s\S]*? or multiline mode across markers
• Declaring a merge done having checked only git status / git log
• No pre-resolution copy and no checkout -m recovery before verifying
• Accepting an executor's merge because their report says "conflicts resolved"
• Typing a merge command without knowing what branch --show-current says
• Reporting a push as done based on the push command's output instead of ls-remote