Team training · Block 6 of 6

Investigation and conflicts

Finding what broke, juggling half-done work, and merging properly

6.1

Reading history

Who last touched this line — `blame`

$ git blame invoice.py
6afb878 (Sam    2026-01-09  1) def total(items):
6afb878 (Sam    2026-01-09  2)     return sum(items)
c584509 (Priya  2026-03-14  3) TAX_RATE = 0.20
9f2ab41 (Priya  2026-04-02  4)     return round(total * TAX_RATE, 2)

Every line tagged with the commit that last changed it. The hash is the payload — feed it to git show and you get the diff, the author, and the message that says why.

blame shows only the last touch. To see what a line was before that, blame the parent: git blame c584509~1 -- invoice.py. Or git log -L :total:invoice.py to watch one function evolve.

kata · investigation

The everyday investigation command — far more common than bisect. The loop is always the same three steps: blame the file, copy the hash on the line you care about, git show that hash to read the reasoning. Stress that blame answers "when and by whom", not "why". The why lives in the commit message and the PR — which is exactly why commandment 10 (write the PR description for the future) pays off here. A good message turns blame into an explanation; a "fix bug" message turns it into a dead end. The fragment is the part people don't know: blame only ever shows the most recent change to a line, so a pure reindent or rename hides the real author. Blame the parent commit (~1) to step back through that line's history; git log -L follows a whole function or line-range across its life. The names are neutral placeholders — keep it about the mechanism, not the person on the line.

When did this text arrive or vanish? — the pickaxe

$ git log -S "TAX_RATE" --oneline    # commits that add or remove the string
c584509 Add tax calculation

$ git log -p -- invoice.py           # every change to one file, diffs inline
$ git show c584509                   # one commit in full: diff, author, message

-S finds where a string was introduced or deleted — "who added this call", "where did this constant go". -G takes a regex instead of a literal.

Blame answers "what's on this line now". The pickaxe answers "which commit changed this text, ever" — even if later commits moved or reindented it.

kata · investigation

The complement to blame. Blame is line-oriented and shows only the latest touch; the pickaxe is content-oriented and finds the exact commit where a string first appeared or was removed, regardless of what happened to that line since. Concrete framing: a function call disappeared and something broke. git log -S "old_function(" walks straight to the commit that deleted it — no scrolling. It's also how you find where a magic constant or config key was introduced. -S counts occurrences of a fixed string and reports commits that change the count; -G matches a regex against the diff text. -S is what you want most of the time. git log -p -- <file> and git show <commit> are the two readers you lean on once blame or bisect hands you a hash: one walks a file's whole history with diffs, the other opens a single commit in full.

Investigate your own moves — the reflog

$ git reflog
9d4e1a7 HEAD@{0}: commit: Cap discount at subtotal
2b8c6f0 HEAD@{1}: reset: moving to HEAD~1
7a1f9c3 HEAD@{2}: commit (amend): Tidy discount helper
1f9a7d2 HEAD@{3}: rebase (finish): returning to refs/heads/feature/discount
a30f5c8 HEAD@{4}: pull --rebase: Fast-forward
8e3b4a6 HEAD@{5}: checkout: moving from main to feature/discount
6d0c2f1 HEAD@{6}: merge feature/tax: Merge made by the 'ort' strategy
f6c6987 HEAD@{7}: checkout: moving from feature/tax to main
c584509 HEAD@{8}: commit: Add tax calculation
b71d3e8 HEAD@{9}: clone: from github.com:acme/pricing.git

Every HEAD movement is journaled — not just commit and reset, but checkout, pull/clone, merge/rebase too. Newest on top; HEAD@{n} counts movements, not commits.

Two things that scale with a real repo: each branch keeps its own reflog (git reflog show feature/discount, or feature/discount@{1}), and you can index by time — HEAD@{yesterday}, HEAD@{2.hours.ago}.

Callback to Block 2, where the reflog rescued a hard reset. Same journal, used here to investigate rather than recover: it's the record of every position HEAD has held, so "what did I actually do this morning?" has a precise answer. Walk the colours once: commits and amend are additive, reset is the one that discards, checkout is pure navigation, pull and clone come from the remote, merge and rebase reshape history. One journal records all of them — if HEAD moved, it's here. Call out a few specifics people ask about: "commit (amend)" and each "rebase (pick)/(finish)" get their own entries, which is exactly why the reflog can rescue a rebase gone wrong — every intermediate state is still named. "pull --rebase: Fast-forward" is one line because nothing needed replaying. The fragment is the genuinely useful part beyond "it exists": per-branch reflogs mean feature/discount@{1} is that branch's previous tip, independent of HEAD; and the time syntax — HEAD@{yesterday}, main@{2.days.ago} — lets you ask "where was this ref before lunch?", which is how you undo something you can't pinpoint by count. Reinforce the two caveats: local only, never pushed or fetched, and a fresh clone starts almost empty (the clone line at the bottom is entry zero of this repo's whole history).

6.2

bisect

It worked in March. It's broken now.

Four hundred commits in between. Which one did it?

Reading four hundred diffs: hours.
Binary search: nine checks.

Marking good and bad

$ git bisect start
$ git bisect bad                 # current commit is broken
$ git bisect good v2.1           # this tag was fine

Bisecting: 187 revisions left to test (roughly 8 steps)

Git checks out a commit halfway between. You test it, and tell git what you found.

$ git bisect good      # or: git bisect bad

kata · bisect

Each answer throws away half the commits

$ git bisect start
$ git bisect bad              # HEAD 8b3f1a9 is broken
$ git bisect good v2.1         # 91ac5d3 was fine
Bisecting: 5 left (~3 steps) — now testing d5f1a83   →   git bisect good
Bisecting: 2 left (~2 steps) — now testing f6c6987   →   git bisect bad
Bisecting: 1 left (~1 step)  — now testing 1a2b3c4   →   git bisect good
Bisecting: 0 left (~1 step)  — now testing c584509   →   git bisect bad
c584509 is the first bad commit

Mark the ends — bad HEAD, good v2.1 — then each round is two moves: git checks out a commit and asks, you test it and answer. Four rounds pin the culprit; nine would pin one in four hundred.

Ten fragments, but they group into three beats: set up, then four rounds of ask-and-answer, then the verdict. Set-up (advance 1, 2): mark the two things you already know — the current HEAD is broken (git bisect bad) and the last release you trust is fine (git bisect good v2.1). Point out the endpoints colouring in; everything between them is now suspect. Each round is deliberately two moves. First git checks out its chosen commit and asks — the amber ring is "this is checked out in your working tree, go test it". Nothing is decided yet. Then you run the test and answer good or bad, and only then does the half collapse. Splitting them mirrors reality: git picks, you judge. Round 1 (3, 4): git names d5f1a83; you test, good; the whole left half is now known-good. Round 2 (5, 6): it names f6c6987; bad; the right clears. Round 3 (7, 8): 1a2b3c4; good; one commit left between the last good and first bad. Round 4 (9, 10): c584509 — bad — and git declares it the first bad commit. Keep stressing: good/bad only means "does the symptom appear". Git never reads the code; each answer is just worth half the remaining history. Same "roughly N steps" countdown as the command slide, now with the graph attached.

The culprit, and getting out

c584509 is the first bad commit
    Add tax calculation

$ git bisect reset          # back to where you started

If you can script the test, git will do the whole thing unattended:

$ git bisect run pytest tests/test_pricing.py

kata · bisect

6.3

stash

Half-finished work, urgent interruption

$ git stash
Saved working directory and index state WIP on main

$ git switch hotfix          # deal with the fire

$ git switch main
$ git stash pop              # pick up where you left off

Stash is a stack. git stash list shows them; pop takes the most recent.

Plain git stash only tucks away tracked changes. A brand-new file you haven't added is untracked — it stays in your working tree and follows you to the other branch.

$ git stash -u     # --include-untracked: sweep up new files too
$ git stash -a     # --all: untracked and ignored (rarely what you want)

kata · basic-stashing

The honest caveat: committing on a throwaway branch does the same job and is harder to lose. Stashes are easy to forget about — people accumulate a dozen and can't remember what any of them were. So: stash for minutes, commit for hours. The untracked gotcha is the one that actually bites, so give it the fragment. Plain git stash stashes tracked changes — staged and unstaged both — but it ignores untracked files entirely. So you stash, switch to the hotfix branch "clean", and your new file is sitting right there, uncommitted, now tangled with the hotfix. git stash -u (--include-untracked) sweeps those in too. Demo it: create a new file, plain stash, show git status still lists it, then stash -u and show a truly clean tree. -a / --all also grabs ignored files — almost never what you want (build output, .env), so mention it only to warn against reaching for it by reflex. Practical tip worth giving: git stash push -m "description" names it, which makes git stash list actually useful. Note push is also the form you need when you want -u with a message.

6.4

cherry-pick

Copying one commit somewhere else

$ git switch main
$ git cherry-pick c584509

A copy, not a move. The original stays where it was.

kata · basic-cherry-pick

6.5

Conflicts, properly

A conflict is not a failure

Git merges automatically when the two sides changed different regions relative to the common ancestor.

A conflict is git saying: both of you changed the same region, and I will not guess which one you meant.

It's a request for a decision, not an error.

Which side is ours?

ours = the base. theirs = the commits stacked on top of it.

Same shape both times: main is the base (ours), feature sits on top (theirs). Only your standing point changes — and a rebase runs from feature, yet feature is still theirs. Unsure? Skip the flags and resolve in the editor.

Placed early, right after "a conflict is not a failure", because ours/theirs is the vocabulary every later conflict slide leans on. It also pre-empts the trap on the escape-hatches slide, where people reach for --ours mid-rebase and take exactly the wrong side. The mechanism is the fix, not memorisation: whoever is the base at the moment of the conflict is "ours". In a merge you're sitting on your branch, so ours is yours. In a rebase you've temporarily moved onto main and are replaying your commits as if they were patches arriving — so the base (main) is ours and your patch is theirs. Practical advice: if you have to think about it, don't use the flags. Open the file and resolve by reading the content, where there's no ambiguity about which line you want. Callback to Block 1's three-way merge: ours/theirs are just the two sides being compared against the common ancestor. Rebase doesn't change what a conflict is, only which label sits on which side.

The same two sides, in the markers

<<<<<<< HEAD          ← ours · the base (main)
TAX_RATE = 0.20
=======
TAX_RATE = 0.175
>>>>>>> feature       ← theirs · stacked on top

The top block, up to =======, is ours (HEAD). The bottom block is theirs. Exactly the two sides from the graph — teal base, rose on top — now in the file.

HEAD is main in both a merge and a rebase. So in a rebase the top block is main's line and >>>>>>> names your own commit — "HEAD" is not "the branch you started on". Read the position, not the label: top is the base, bottom is what's arriving.

The bridge from the concept to the thing they actually stare at. Map it once, explicitly: everything between <<<<<<< and ======= is HEAD — ours, the base. Everything from ======= to >>>>>>> is the incoming side — theirs. Same teal and rose as the previous graph, deliberately, so the colour carries the idea across. Then the reversal restated in marker terms, because this is exactly where it bites. HEAD at the top is whatever git currently has checked out as the base. In a merge that's your branch; in a rebase git has checked out main and is replaying your commits, so HEAD is main and the >>>>>>> label is one of your own commit subjects. People read "HEAD" as "me" and grab the wrong block — tell them to trust the position, not the name. Sets up the next slide: they now know which block is which, but neither block tells them what the line STARTED as — which is the gap zdiff3 fills.

The default markers hide the useful part

All you're shown are the two tips — main's 0.20 and feature's 0.175. The ancestor they both diverged from is dropped, so you can't tell which side actually changed the line.

Did someone raise it from 0.175, or lower it from 0.20? The answer changes the decision entirely.

Turn on `zdiff3`. Once. Forever.

$ git config --global merge.conflictStyle zdiff3

<<<<<<< HEAD
TAX_RATE = 0.20
||||||| common ancestor
TAX_RATE = 0.175
=======
TAX_RATE = 0.175
>>>>>>> feature

The ancestor block is the amber box, now in the file. Main raised it; feature never touched it. Keep ours.

Reduce conflicts — trailing commas

Two branches touch one list: A appends an item, B renames the last one.

✗ no trailing comma

scopes = [
    "read",
<<<<<<< append
    "write",
    "delete"
=======
    "admin"
>>>>>>> rename
]

To append, A had to add a comma to the "write" line — the exact line B renamed. Same line, two edits → conflict.

✓ trailing comma

scopes = [
    "read",
    "admin",     # B: renamed
    "delete",    # A: new line
]

The comma was already on "write", so A's append is a brand-new line and B's rename touches a different line. Git merges both — no conflict.

First of two prevention slides, and the highest-leverage idea in the section — you can't out-resolve conflicts you keep manufacturing. Walk the mechanism, don't just assert it. Without a trailing comma the last element has no comma, so appending is really TWO edits: add a comma to the previous last line, then add your line. That first edit is the trap — it drags an unrelated line (the one someone else may be renaming, reformatting, or removing) into your diff. Here B renamed "write"; A's append also modified "write" just to add the comma, so the two collide on a line neither of them meant to fight over. With the trailing comma already present, appending is a pure single-line addition. A never touches "write", so B's rename merges cleanly. Same two changes, zero conflict — the only difference is one comma that was there ahead of time. Say the general rule: put the trailing comma on multi-line lists, objects, arguments, enums — anywhere the language allows it. It also makes every append a one-line diff, which reviewers thank you for. Next slide is the companion: ordering, for when both changes are additions.

Reduce conflicts — sort your lists

Now both branches do the same thing: each adds a dependency.

✗ appended at the end

deps = [
    "flask",
    "requests",
<<<<<<< add aiohttp
    "aiohttp",
=======
    "urllib3",
>>>>>>> add urllib3
]

Both new lines land in the same spot — the end — so git can't tell them apart. Conflict.

✓ kept alphabetical

deps = [
    "aiohttp",    # A: sorts to top
    "flask",
    "requests",
    "urllib3",    # B: sorts to bottom
]

Alphabetical order sends each addition to a different line. Git drops both in and merges without a word.

The companion case: when both changes are additions, a trailing comma isn't enough — two appends still land at the same point and collide. Ordering is what saves you. The mechanism: if the list has a deterministic order (alphabetical here), a new entry has exactly one correct place, and two unrelated additions almost always sort to different lines. Git merges non-adjacent insertions automatically, so the conflict never happens. Append-to-the-end is the opposite: it funnels every addition to the same line, which is why "everyone edits the bottom of the imports" is a perennial conflict. Apply it to imports, object/dict keys, enum members, dependency lists, route tables — anything that's really a set. Most formatters and linters can enforce it (isort, eslint sort-imports, etc.), so it's free once configured.

Reduce conflicts — more habits

Same principle as the commas and the sorting: keep every change small, local, and canonical.

Habit	Why it cuts conflicts
One item per line	Each change is its own line, so two edits can't overlap
A shared auto-formatter on save (prettier · black · gofmt)	Everyone's output is byte-identical — no whitespace or reflow conflicts, and minimal diffs
Never hand-edit generated files or lockfiles	Regenerate them — the tool owns the format, not you
Union-merge append-only files (`CHANGELOG.md merge=union` in `.gitattributes`)	Git keeps both sides automatically instead of conflicting

Block 5's rule, one more time: the cheapest conflict is the one you never create. Short branches + code that merges cleanly removes most of them before they start.

The general versions of the two specific tricks — take them one at a time. One item per line: same reason as the trailing comma — keep every change on its own line so it can never overlap another. Applies to arrays, arguments, JSX props, SQL column lists, anything list-shaped. Shared auto-formatter: agree it once (prettier, black, gofmt, rustfmt) and run it on save or as a pre-commit hook. Byte-identical output means whitespace, wrapping and quote style stop being things two branches can disagree about — a whole category of noise conflicts vanishes and diffs shrink to the real change. The one rule: everyone runs the same version, or the formatter itself becomes the conflict. Generated files and lockfiles: never resolve them by hand — the merge markers land inside machine-generated syntax and you'll corrupt it. Delete and regenerate (npm install, cargo build, protoc) and commit that. Union merge: for files that only ever grow — a changelog, a feature-flag list, an allowlist — a line in .gitattributes (path merge=union) tells git to keep both sides of a conflict instead of stopping. Perfect when order doesn't matter and the only real risk is losing an entry. Close on Block 5 again: age is one axis of conflict pain, surface is the other. Short branches attack the first; everything in these two slides attacks the second.

Stop resolving the same conflict twice

$ git config --global rerere.enabled true

Reuse recorded resolution. Git remembers how you resolved a conflict and reapplies it automatically next time it sees the same one.

Useful during a long rebase where the same conflict recurs commit after commit. Set it and forget it.

Escape hatches

$ git merge --abort        # put everything back
$ git rebase --abort       # same, mid-rebase
$ git checkout --ours file    # take our whole version
$ git checkout --theirs file  # take theirs

During a rebase, "ours" and "theirs" are reversed from what you'd expect — you're replaying your commits onto their base, so "ours" is the branch you're rebasing onto.

That's the course

Block	The one-line version
1 — Local model	Three trees, snapshots, pointers
2 — Recovery	Almost nothing is ever really lost
3 — Rewriting	New commits, not edited ones
4 — Remotes	`origin/main` is your note about the server
5 — Team workflow	Short branches, small PRs, authors own them
6 — Investigation	Tools for when it goes sideways

Handout: the 13 commandments. Slides and katas are in the repo — the speaker notes have every command.

The 13 commandments

01Commit early, commit often.
02One logical change per commit. If the message needs an "and", it's two.
03Read your own diff before you commit.
04Never rewrite history someone else has pulled.
05Force push only your own branch — with --force-with-lease.
06Revert in public, reset in private.
07Keep your branch current with main.
08Never commit secrets, build output, or dependencies.
09When it looks broken, stop. reflog, then ask.
10The PR description is the permanent record.
11Keep PRs small enough to review in one sitting.
12You opened it, you own it.
13After a squash merge, delete the branch and re-branch from main.

Nine follow from how git works. Four are ours to change. The printable handout is in the repo.