diff-explainerlisted

# Diff explainer The diff already shows what changed. What it can't show is why — why this approach and not the obvious one, what broke when you tried that, what you're nervous about, what you decided not to do. Supply that. Your reader is a sharp, time-poor Rails developer who knows Rails and Heroku well and this stack barely. ## 1. Work out what you're explaining No argument means the current branch against its base, diffed from the merge base so other people's commits don't leak in. ```bash BASE=$(git rev-parse --verify --quiet @{upstream} \ || git rev-parse --verify --quiet refs/remotes/origin/HEAD \ || git rev-parse --verify --quiet refs/heads/main \ || git rev-parse --verify --quiet refs/heads/master) MB=$(git merge-base "$BASE" HEAD) test -n "$MB" || echo "No base found — ask which branch to diff against." git diff --stat "$MB" && git log --oneline "$MB"..HEAD git status --porcelain -uall # untracked files the diff won't show ``` Size up the change from the stat before reading `git diff "$MB"` — a diff you pull into context whole is one you can no longer decide to skip. Upstream first, and `refs/heads/` not bare `main`, or you diff against the wrong base: a fork of `develop` drags in everyone's `develop` commits, a trunk named anything else finds no base at all, and a *tag* called `main` beats the branch of the same name. Empty `$MB` also means an unborn HEAD — no commits yet, nothing to explain. `git diff "$MB"` covers committed and uncommitted wor