From 4278eeb607f86f5538c2b3e930049f14bfb8e214 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Fri, 13 Nov 2026 20:15:42 -0400 Subject: [PATCH] =?UTF-8?q?pre-pr-checks:=20a=20stale=20branch=20read=20as?= =?UTF-8?q?=20a=20revert=20=E2=80=94=20the=20reviewer's=20side=20of=20the?= =?UTF-8?q?=20merge-base=20section?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three reviewers in one night (2026-11-13) read `git diff --name-status origin/main ` as "this branch reverts X": #2021 said the merge reverts #2368, #2369 said the branch deletes a file it should keep, #2387 said it would revert #2366/#2386's audio work. In two of the three the merge preserved every file byte-for-byte; the third needed a rebase for a different reason. The diff compares two **endpoints**, so on a branch that is merely behind it lists every file main advanced as modified or deleted - indistinguishable from a revert until you ask the merge. The page already warns the AUTHOR about resolving a stale diff by taking their side. This adds the same phenomenon from the other direction, with the two commands that separate the cases and cost nothing: git diff --name-status origin/main... # three dots: the branch's own changes vs its merge base git merge-tree --write-tree origin/main # what the merge would produce and the one that identifies a real revert: `git log --oneline origin/main.. -- ` empty means the branch never touched it. Rebasing is still worth doing; *hold* and *stale* are different verdicts. --- docs/pre-pr-checks.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/pre-pr-checks.md b/docs/pre-pr-checks.md index c294f3b44..32a38396c 100644 --- a/docs/pre-pr-checks.md +++ b/docs/pre-pr-checks.md @@ -121,6 +121,32 @@ carried an already-merged commit for the same reason. side drops them; rebase and keep every row `main` has; - **stale and clean** — behind, not destructive: the merge keeps `main`'s rows. Rebase when convenient. +### The same thing read from the reviewer's side: a stale branch is not a revert + +`git diff --name-status origin/main ` compares **two endpoints**, so on a branch that is merely behind it lists every file +`main` advanced as *modified or deleted* — including files the branch never touched. That output is indistinguishable from a branch +that reverted them, and on 2026-11-13 three reviewers in one night read it as a revert: #2021 ("the merge reverts #2368"), #2369 +("the branch deletes a file it should keep") and #2387 ("would revert #2366/#2386's audio work"). In two of the three, the merge +preserved every file byte-for-byte. + +Two commands separate the cases, and neither needs the branch checked out: + +```bash +git diff --name-status origin/main... # three dots: the branch's OWN changes, against its merge base +git merge-tree --write-tree origin/main # what a merge would actually produce +``` + +If the three-dot diff lists only files the PR means to change, and the merged tree's copy of the suspect files is identical to +`main`'s, the branch is **behind, not reverting** — a merge or squash takes its diff from the merge base, which contains neither the +missing files nor a deletion of them. The case it *is* a revert is easy to tell apart too: + +```bash +git log --oneline origin/main.. -- # empty = your branch never touched it +``` + +Rebasing is still worth doing for a stale branch — a rebased head makes the endpoint diff self-evident to the next reader and costs +one command — but *hold* is a different verdict from *stale*, and the difference is one `merge-tree` away. + ## The one that is not a command: build the target that contains the file you edited Nothing above compiles anything, and a green `build` tick does not answer this question either -- it answers "the targets CI built