diff-explainer

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 developer who may not know this stack.

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.

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 work both, so a branch with no commits of its own still works. An argument overrides. Resolve it as a rev first (git rev-parse --verify --quiet <arg>); anything else is a path, and goes after -- so a docs branch and a docs/ directory can't collide. A bare number is a PR (gh pr diff <n>, plus gh pr view <n> for the body and linked issue) unless a branch by that name exists; with no working gh, say so and take the branch. If the change is obvious — a version bump, a typo — say so and skip the artifact.

2. Who's reading