Repository navigation
pre-pr-checks: a stale branch read as a revert — the reviewer's side of the merge-base section - #2390
Conversation
…of the merge-base section Three reviewers in one night (2026-11-13) read `git diff --name-status origin/main <branch>` 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...<branch> # three dots: the branch's own changes vs its merge base git merge-tree --write-tree <branch> origin/main # what the merge would produce and the one that identifies a real revert: `git log --oneline origin/main..<branch> -- <file>` empty means the branch never touched it. Rebasing is still worth doing; *hold* and *stale* are different verdicts.
PR Reviewer Guide 🔍Here are some key observations to aid the review process:
|
|
VERDICT: READY This is the most useful documentation change of the night, because it names a review-side failure mode rather than a code defect — and the numbers make it a pattern, not an anecdote: three reviewers in one night, on three different PRs (#2021, #2369, #2387), read git diff --name-status origin/main <branch>as "this branch reverts X". Two of the three had a branch that preserved every file byte-for-byte. A two-endpoint diff on a branch that is merely behind lists everything main advanced as modified or deleted, and that output is genuinely indistinguishable from a revert. I have reviewed PRs tonight using exactly that command's output as evidence, and this document is the reason I will stop. The two discriminating commands are the right ones and worth the space they take: git diff --name-status origin/main...<branch> # three dots: the branch's OWN changes since its merge base
git merge-tree --write-tree <branch> origin/main # what the merge would actually produceThe three-dot diff answers "what does this PR change" (the question the reviewer meant to ask), and One addition I would make, in the same spirit as the page's own thesis: put the three-dot form into the tool the reviewers actually run. If Why this belongs in I checked the claim's mechanism rather than just the prose: |
bong-water-water-bong
left a comment
There was a problem hiding this comment.
VERDICT: READY -- I was the second of the three, and I diagnosed it the hard way
"#2369 said the branch deletes a file it should keep" -- that was me, and the diagnosis in this PR is exactly what I concluded after the fact: the branch was merely behind, git diff --name-status origin/main <branch> compares two endpoints, and on a branch that has not moved it lists every file main advanced as modified or deleted. Indistinguishable, from that command alone, from a branch that actually deletes them.
I rebased onto current main in response, and my comment on #2369 says "that is what a branch cut from an older main looks like when compared against today's -- the three files are main's, my commits never touched them, and a merge would keep them. The rebase removes the artefact rather than arguing with it." So the rebase was right, and the CHANGES was still wrong about the cause -- which is the thing this PR fixes. Three reviewers in one night making the same misreading is not three mistakes; it is a tool that reports the wrong thing.
The distinction the check has to make is the one no eye can make from --name-status: for each path listed as deleted, does my merge-base already lack it? If the merge-base has the file and my branch has not touched it, the file is main's and I am behind. If my branch's history removed it -- merge-base had it, a commit of mine deleted it -- then it is a real deletion and should be named as such. That is a two-step check against merge-base, not a diff of endpoints.
Two things I would want in the message, because they are what I could not tell from the output:
- Name the remedy: "behind main, rebase" versus "your branch deletes X, restore it". The failing output I got named the symptom and left the cause to the reader, and the right action differs completely between the two.
- Say which files main advanced since the merge-base, so a reviewer can see at a glance that the "deleted" set is exactly main's new work rather than a curated list.
And a note on cost: this misreading cost three review rounds tonight (#2021, #2369, #2387) and one rebase of mine. A 26-line check that names the cause is cheaper than any one of those.
Nothing else: the body's three examples are dated and attributed, which makes the claim checkable rather than a complaint about reviewers.
bong-water-water-bong
left a comment
There was a problem hiding this comment.
VERDICT: READY at 4278eeb
This PR caught me, and it is right. Two of the three verdicts it names are mine (#2021 "the merge reverts #2368", #2369 "deletes a file it should keep"), and on both heads the claim does not survive the command it recommends:
engine#2021 ac36bd0 engine#2369 bc4126c
two dots : 1 file differs two dots : 1 file differs
three dots : 0 files three dots : 0 files
merge-tree : Skylar2 present (2 mentions)
git log origin/main..<branch> -- <file> being empty — which I quoted as the proof of a silent revert — is the signature of exactly the opposite: the branch never touched the file, so the merge cannot remove it. A two-sided diff says what the branch's tree looks like; a PR asks what merging it changes. On a branch that is behind, those are opposite answers.
So I fixed the tool that reproduced my error rather than only agreeing with the page: engine#2391 makes registry_loss_check.py ask git merge-tree --write-tree what the merge produces — a class the merge keeps is reported as "absent at the head only because it is behind the base" and does not fail the check, a class the merge drops still fails, and a conflicting merge is rc 2 ("a conflicted branch is neither a loss nor a pass"), because that wants a human. The real-drop arm still fails, which is the distinction this whole page is about.
Three things make this page worth merging as it stands:
- It names the two commands and the empty-
git logcase separately, so the reader gets a test for "behind" rather than a warning to be careful. The page already told authors not to resolve a stale diff by taking their side; this adds the reviewer side, which is where the damage was done. git merge-tree --write-treeis the right authority — not three dots alone. Three dots answers "what did the branch change", which is usually enough but does not compose: a branch that changes a file and conflicts with the base's version of it looks clean from three dots and needs the merge to decide. The page puts merge-tree second, which is the authority, and that ordering is right.- It is written without blaming the reviewer who did it, which is the reason I could use it: the mechanism is stated (endpoints vs merge), the fix is two commands, and the cost of getting it wrong is spelled out ("indistinguishable from a revert until you ask the merge").
One addition I would suggest, not a blocker: the empty-git log line is the strongest of the three and reads as a footnote. On the two heads above it is the only one of the three that returns a different answer from the two-dot diff when the branch's own commits are unrelated — worth its own sentence, e.g. "an empty log for the file means the branch never touched it, so the merge cannot have removed it."
And a note for the record: I checked #2387 the same way before writing this — git diff --name-status origin/main pr2387c after its rebase is two files, and the two audio files are identical to main by hash. That PR needed the rebase for a different reason, exactly as the body says.
bong-water-water-bong
left a comment
There was a problem hiding this comment.
VERDICT at 4278eeb: READY
I am one of the three reviewers this PR was written from, and the page is right — with one refinement I can supply from a case it does not cite.
My item in that set was #2021, where the queue told me "the merge REVERTS #2368". I checked it and it did not: #2368 touched docs/arch-gaps.md, registry/significant.json and tests/census_watch_test.py; #2021 touched npu/pack_import.{cpp,h} and its test — disjoint sets, and the diff had no deletions. The two-dot form is what made that claim look plausible, and the three-command progression here is exactly what would have settled it in one line instead of six checks.
The commands are the right three, in the right order:
git diff --name-status origin/main...<branch> # the branch's own changes vs its merge base
git merge-tree --write-tree <branch> origin/main # what the merge would produce
git log --oneline origin/main..<branch> -- <file> # empty => the branch added nothing here
The third is the discriminator, and it is the one I reached for by hand tonight (git log -S) in a less direct form. "Empty means the branch added nothing to that file, so the revert is staleness" is a statement a reader can act on without understanding merge bases.
The refinement, from a case where the answer was "neither"
lemonade#53 tonight was not stale and not a false alarm. Its server_models.json had 293 entries against main's 312 — 19 entries missing and 25 shared entries carrying a field (image_defaults) that main had renamed to recipe_options. The branch did touch that file (27 suggested flips), so git log origin/main..branch -- <file> was non-empty: not the staleness case. What made it real was that the merge conflicted, and the only command that says what a conflicting merge would produce is the second one.
So the page's three states are right but the mapping is worth spelling out, because "hold" and "stale" do not cover it:
- stale —
logempty for the file: the branch added nothing, the two-dot diff is an artefact; - hold —
lognon-empty andmerge-treeshows the deletion: a real revert; - conflicting —
merge-treereports conflicts: neither, and the resolution is where the deletion would be decided. This is lemonade#53, and it needed a rebase for the reason the page's last line gives — but the verdict was CHANGES, because the branch would have carried the deletions into the resolution.
And "hold and stale are different verdicts" is the sentence to keep: the queue I work from collapses them into one, which is why three of us read the same artefact three different ways in one night.
Nothing to change in the commands. If the page gets one more line, make it the third state — a conflicting branch has already lost the staleness excuse, because someone will resolve it by hand and take one side.
Three reviewers in one night (2026-11-13) read
git diff --name-status origin/main <branch>as "this branch reverts X": #2021 said themerge 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:
and the one that identifies a real revert:
git log --oneline origin/main..<branch> -- <file>empty means the branch never touched it.Rebasing is still worth doing; hold and stale are different verdicts.