Skip to content
Clawdemy

Merge conflicts

What this lesson covers

Section titled “What this lesson covers”

L7 teaches the mechanical resolution of merge conflicts and surfaces the dangerous semantic-conflict category that git cannot detect.

Five load-bearing ideas:

  1. A merge conflict is git asking you a question. “Both branches changed these lines in different ways; please tell me which version you want.” That’s the entire transaction.

  2. The six-step resolution process is mechanical. Recognize merge state, find markers, decide, edit, stage, commit. Only step 3 (the decision) requires judgment. Everything else is rote.

  3. diff3 conflict style is strictly better than the default. Showing the common ancestor makes the right resolution obvious in most cases. Enable it once globally; never look back.

  4. There are five conflict types, not one. Textual (the obvious case), logical-combine (both changes needed), semantic (textually compatible but logically incompatible, git can’t detect), delete-modify (file existence dispute), rename-edit (structural change collides with content change). Each has a different fix.

  5. git merge --abort is not failure. It’s taking a do-over with better information. Use it whenever the conflict surface is too large to handle calmly.

By the end of L7, the reader will be able to

Section titled “By the end of L7, the reader will be able to”
  • Recognize when git is in a merge state and locate conflicting files
  • Read default and diff3 conflict markers fluently
  • Apply the six-step resolution process
  • Identify which of five conflict types they’re facing and choose the correct fix
  • Decide between resolving forward and aborting (git merge --abort)
  • Articulate why semantic conflicts are dangerous and what discipline catches them
  • Apply five conflict-prevention disciplines

Prerequisites

Section titled “Prerequisites”
  • L1 (snapshot mental model)
  • L2 (commits)
  • L3 (commit hygiene)
  • L4 (undoing things): recovery toolkit comforting when first learning conflicts
  • L5 (branches)
  • L6 (pull requests): conflicts often surface in PR review
  • A real repository to practice on
  • A teammate (or two terminals on your own machine) to simulate concurrent edits

Reading map

Section titled “Reading map”

L7 is content-dense by design. Read it in three passes:

Pass 1: The basics. Why conflicts happen + reading markers + the six-step process. After this, you can resolve trivial conflicts.

Pass 2: The worked examples. Six concrete scenarios across textual, logical, delete-modify, semantic, and rename-edit conflicts. After this, you’ve seen most of the conflict types you’ll encounter.

Pass 3: The discipline. Tools, when to abort, prevention strategies, scaling across team sizes, the multi-agent foreshadowing. After this, you have the full mental model.

New developers should walk through all three passes, slowly. Even one practice conflict on your own machine builds 10x more confidence than reading alone. The practice section is designed for this.

Experienced developers should focus on the semantic-conflict section and the multi-agent foreshadowing. The mechanics are review; the dangerous-conflict category and the AI-scale workflow are new framings.

Managers and TPMs should read the dedicated framing section. Conflict rate as a leading indicator of branch hygiene is operationally useful.

What this lesson deliberately does not cover

Section titled “What this lesson deliberately does not cover”
  • Rebase mechanics (deferred to L12; rebase has its own conflict-handling specifics)
  • Cherry-pick conflicts (deferred to L11; same mechanics, different surface)
  • Git’s strategy options (-X ours, -X theirs, recursive, octopus): advanced and rarely needed; mentioned in passing
  • Resolving conflicts in binary files (rare; tooling-dependent; deferred)
  • Conflict resolution in distributed/federated workflows (covered in L15 with worktrees)

If you want rebase conflict mechanics, L12 is next. If you hit a binary file conflict, your editor or tool handles it; no general process to learn.

Estimated reading + practice time

Section titled “Estimated reading + practice time”

35 to 45 minutes for reading (the worked examples each take 2-3 minutes to absorb). 25 to 35 minutes for the practice exercises (includes the most pedagogically valuable drill in T7: deliberately creating a merge conflict in a sandbox, resolving it three different ways).

Total: about 60 to 80 minutes including practice. The investment is concentrated; the payoff is conflict fluency for years.