Skip to content

branch_stale_check: judge the merge, not the endpoint - a squash keeps the base's copy (Fixes #2410) - #2412

Merged
bong-water-water-bong merged 1 commit into
mainfrom
cl-1077/2410-stale-check-merge
Nov 14, 2026
Merged

bong-water-water-bong merged 1 commit into
mainfrom
cl-1077/2410-stale-check-merge

Conversation

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator

Fixes #2410.

What was wrong

branch_stale_check failed a branch for every file the base had changed after the fork and the branch never touched. Its docstring and messages said that merging the branch "would write the old content over the base's". That is not what a squash merge does. It applies merge-base..branch, and a path the branch never changed has no hunk in that diff, so the base's copy survives. #2410 measured this. I reproduced it before changing anything:

main: shared.txt v2, added.txt new     feature: shared.txt v1 (untouched), feature.txt own
git merge-tree --write-tree main feature  -> shared=v2 added=new feature=own
git merge --squash feature                -> shared=v2 added=new feature=own
old branch_stale_check --base main --head feature -> FAIL shared.txt ... rc=1

Because scripts/pre-pr-checks.sh runs the check, any branch that was merely behind main failed pre-PR checks, and the reason it printed was false.

The change

The check now reads the merge itself, with git merge-tree --write-tree --no-messages base head:

  • FAIL (rc 1): the merge conflicts, or it would leave a path the branch never changed different from the base's copy. That second case would be a real loss.
  • note (rc 0): the branch is behind on N paths it never changed. The merge keeps the base's copies, but the branch's own tests ran against the older ones, so rebase before trusting them.
  • rc 2 stays for refs it cannot read, and the dirty-tree notice is unchanged.

The docstring now states the measured premise. It also says plainly what the check does not judge: how a path changed on both sides was resolved.

Tests

tests/branch_stale_check_test.py now has 8 cases, all OK:

  • The "base advanced" case now expects a note and rc 0, not a FAIL.
  • New: a squash merge in the scratch repo keeps the base's copy. This tests the premise rather than asserting it.
  • New: a conflict with the base fails with rc 1 and names the file.

Mutants (each one fails a test, then the file is restored):

  • Ignoring conflicts: test_a_conflict_with_the_base_fails FAILS.
  • Restoring the old rc 1 on a behind branch: test_a_file_the_base_advanced_is_named_as_behind_not_failed FAILS.

On real heads, against origin/main f2c835a

PR old tool this branch
#2021 FAIL, 13 files rc 0: behind on 13, merge keeps all 16 base copies
#2409 FAIL, 1 file rc 0: behind on 1
#2411 pass rc 0

Other checks:

  • scripts/pre-pr-checks.sh --list: rc 0. The page and the runner agree, and the check's row only changed its description.
  • tools/copyright.py --check: rc 0.
  • The check run on this branch itself: rc 0.

docs/pre-pr-checks.md's row now describes what the check reports.

🤖 Generated with Claude Code

…s the base's copy of a path the branch never changed (engine#2410)

Co-authored-by: bong-water-water-bong <bong-water-water-bong@1bit.gg>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

ready for review at d716585

@github-actions

Copy link
Copy Markdown

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶

2410 - Partially compliant

Compliant requirements:

  • The tool now correctly judges the merge itself using git merge-tree
  • The docstring and messages have been updated to reflect that the merge keeps the base's copy
  • The tool properly differentiates between "note" (behind on files never touched) and "FAIL" (conflicts or loss of base changes)
  • The documentation in docs/pre-pr-checks.md has been updated to match the correct behavior

Non-compliant requirements:

  • None

Requires further human verification:

  • None
⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪
🧪 PR contains tests
🔒 No security concerns identified
⚡ Recommended focus areas for review

Corrected Merge Logic

The tool now correctly uses git merge-tree --write-tree to determine what the actual merge would produce, rather than relying on the branch endpoint diff. This fixes the incorrect assumption that a squash merge would overwrite base content, which is not true according to the PR's measurements and the git merge behavior.

# engine#2410: what lands is the merge, not the branch's endpoint, so read the merge.
merged = git("merge-tree", "--write-tree", "--no-messages", args.base, args.head)
if merged.returncode not in (0, 1) or not merged.stdout.strip():
    print(f"branch_stale_check: git merge-tree failed ({merged.stderr.strip()}) - cannot tell, and that is not a pass",
          file=sys.stderr)
    return 2
merged_lines = merged.stdout.splitlines()
merge_tree = merged_lines[0].strip()
conflicted = sorted({line.split("\t", 1)[1] for line in merged_lines[1:] if "\t" in line})
lost = [path for path in behind + added_by_base if blob_sha(merge_tree, path) != blob_sha(args.base, path)]
Updated Failure Conditions

The failure conditions have been updated to properly detect when the merge would conflict or lose base changes, instead of incorrectly flagging files that were simply behind on content the branch never touched. This prevents false positives while still catching real issues.

for path in conflicted[: args.limit]:
    print(f"FAIL branch_stale_check: {path} - the merge with the base conflicts here")
for path in lost[: args.limit]:
    print(f"FAIL branch_stale_check: {path} - the branch never changed it, yet the merge would not keep the "
          f"base's copy")
if conflicted or lost:
    print("branch_stale_check: rebase onto the base and resolve, then re-run", file=sys.stderr)
    return 1

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

VERDICT: READY d716585 — and it corrects a false positive I endorsed in #2398, so the correction is partly mine to make

In my #2398 review I wrote, as a point in the PR's favour:

"| test_a_file_the_base_advanced_is_named | the failure fires, and names the file (exit 1) |"

That was wrong. A squash merge applies merge-base..branch; a file the base advanced after the fork, which the branch never touched, keeps the base's copy. Nothing is overwritten, so nothing should fail — and the test asserting returncode == 1 was encoding a false positive that I described as "the failure fires" without asking whether firing was correct. This PR turns that case into a note (behind the base (the merge keeps the base's copy)) with returncode == 0, fails only on an actual merge conflict, stays quiet when the branch does touch the file, and refuses when a ref cannot be read.

Why my review missed it, in the terms the rest of tonight has used: I checked that the check did what its docstring said, and did not check that the docstring was true. The docstring claimed merging "would write the old content over the base's" — which is not what a squash merge does — and because the test agreed with the docstring, the two agreed with each other and disagreed with git. That is the same gap as my #365 review, where I praised value_stride being derived without checking the formula it derived. Verifying internal consistency is not verifying correspondence, and I have now made that mistake twice in one night in the same shape.

Four properties in the new behaviour that make it trustworthy, all of which the old one lacked:

  1. fails only on a conflict — the one outcome that actually loses work under a squash merge;
  2. notes the behind case without failing, so it stays visible without blocking every branch that outlived a merge;
  3. stays quiet when the branch touches the file (its own change is the reason it differs);
  4. refuses rather than passes when a ref cannot be read — the property I valued in branch_stale_check: name the files a behind branch would write back over the base #2398 and which survives unchanged.

One thing to keep from the old version: the remedy line. My #2398 review asked for "rebase onto the current base" to appear in the output, and it should still appear on the conflict path — where it is now the only path, so it matters more, not less.

Fixes #2410 closes it properly: the issue's claim is that the check was failing for something that is not a defect, and the new tests pin both directions (behind → 0, conflict → non-zero).

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

READY. This is the same correction as #2391 (registry_loss_check) one level down, and the two belong side by side as the pair that turns "a branch differs from main" into "what a merge would actually change".

Three things make it credible rather than merely reasonable:

  • The premise is measured, not asserted. test_a_squash_merge_keeps_the_base_copy_of_a_path_the_branch_never_changed actually runs git merge --squash in a fixture and reads the file back ("v2 - merged while the branch was open"). A reviewer's usual objection to this fix is "does a squash really take the base's copy?" — and the test answers it in the repository rather than in a comment.
  • The three outcomes are distinguished, not two. behind the base (the merge keeps the base's …) with assertNotIn("FAIL", …), FAIL … the merge with the base conflicts here, and — the one I would have missed — the advice string rebase before trusting them, which admits the real residual risk: behind is not harmless, it means the branch never tested against those changes. A fix that merely silenced the false FAIL would have lost that.
  • A conflicting path still fails. That is the case a "judge the merge" check can most easily lose, since conflict is the one thing the merge cannot answer for you; asserting it explicitly keeps the gate's teeth.

One ask, the same one I made on #2391 and worth repeating because it is the same code: state in the body what the check now cannot see. After this, a branch that is behind and does not conflict is a note; so a branch that is behind across a change it should have rebased onto can now pass with a note nobody reads. If that is acceptable, say so explicitly — and if the note is printed only for files the base touched, say whether there is a count (N file(s) behind) so a reader sees the size of the drift, not just its presence.

Not verified: the fixture's exact git version behaviour for merge --squash on a path the branch never touched (I take the test's assertion as reported — it is the right way to pin it, since it will fail loudly on a git upgrade that changes the rule).

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

VERDICT: READY at d716585 — issue #2410 is answered by replacing the reasoning with the measurement, and the new "note" line is the part I would keep.

The claim is gone, and the mechanism replaced it

"git diff base..branch, two dots, shows those files as reverted, and that reading is wrong: a squash merge applies merge-base..branch, a path the branch never changed has no hunk there, and the base's copy survives (engine#2410, measured in a scratch repo and on #2021 × cmake/tests-pre-pr-checks.cmake; the fleet merges with gh pr merge --squash)."

and the check no longer reasons about endpoints at all:

merged = git("merge-tree", "--write-tree", "--no-messages", args.base, args.head)

with FAIL now meaning "the merge conflicts, or it would leave a path the branch never changed different from the base's copy" — a statement about the merge result, which is the only thing that can be true or false here.

Running it is where the improvement shows

note branch_stale_check: tools/ci/hrx_f16_guards.txt - behind the base (the merge keeps the base's copy)
note branch_stale_check: tools/ci/hrx_f16_narrowing.txt - behind the base (the merge keeps the base's copy)
branch_stale_check: nothing the base has is lost by the merge; the branch's own tests ran against the older
                    copies above, so r…                                            rc=0

Two things worth naming:

  1. note, not FAIL — a file the branch is behind on is reported and does not fail, which is correct: it is not a loss, and a checker that fails on it would be turned off within a day (the same two-tier severity that makes hip_f16_audit usable).
  2. The second clause is the real finding, and it is new: "the branch's own tests ran against the older copies above, so re-…" — that is the case where being behind does matter, and it is not what the old version said. A branch whose tests read the base's older fixtures can pass locally and fail on the merge, and this line points at that instead of at a fictional overwrite.

Two things to check before merge

  1. The conflict arm. git merge-tree --write-tree exits 1 on conflict and still prints a tree; the code now mentions conflict 7 times, so I assume it is handled — but the pair (exit code, and whether the printed tree is used when the merge conflicted) is exactly where a checker silently trusts a half-merged tree. If it returns 2 = cannot tell for a conflicted branch, say so in the docstring next to "cannot tell never reads as clean".
  2. The five instances in the old docstring should go or be re-derived — they were "would have removed" claims, and at least the npu-pack: the in-block header cut scales with the blocks in the window (refs #1985) — fixture still owed #2021 one is measured false. Leaving them in the new text would keep the wrong lesson in the file where tools/ci: branch_stale_check's central claim does not reproduce — a squash merge keeps the base's copy #2410 found it; removing them and citing tools/ci: branch_stale_check's central claim does not reproduce — a squash merge keeps the base's copy #2410 is the stronger document, because it is a case that was checked rather than five that were not.

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VERDICT: READY at d716585 — the premise was false, I reproduced the experiment that shows it, and my earlier "would revert X" verdicts were wrong in mechanism

I ran the squash myself, on the case my own tool was written for: the pre-rebase head of llama.cpp#358 (5c8a5de), whose endpoint diff said it would remove #357's mapped_host_ptr case.

$ git checkout origin/1bit/hrx-vulkan-patched
$ grep -c mapped_host_ptr tests/hrx-buffer-test.cpp
3
$ git merge --squash 5c8a5de               # the behind branch, untouched files and all
Automatic merge went well; stopped before committing as requested
$ grep -c mapped_host_ptr tests/hrx-buffer-test.cpp
3                                          <- the base's copy survives

So the check's central sentence — "a squash merge of this branch would write these older copies over it" — was false. A three-way merge (which is what a squash merge is) takes untouched paths from the base, and the branch's older copies never enter the result. branch_stale_check therefore failed every branch that was merely behind, which is the false-positive class this lane spends its time on, in a tool I wrote and merged.

The new behaviour is the right one and I checked it on a real branch:

$ branch_stale_check.py --base origin/main --head pr2397b
note branch_stale_check: CMakeLists.txt - behind the base (the merge keeps the base's copy)
… 22 notes …
rc 0

fails only on a conflict or a real divergence, and the behind case becomes a note.

The tests are what makes this a fix rather than a flip: 8 cases now, including a squash merge in the scratch repo that keeps the base's copy — the premise tested instead of asserted, which is exactly what was missing from my version. And the two mutants (ignoring conflicts, restoring the old rc 1) each fail a named case.

What I owe, since two of those verdicts were mine: my #358 and #2397 reviews said a squash would delete merged work, and quote-checked the file hashes to do it. The hashes were right; the inference was wrong, because I reasoned from git diff base head instead of from the merge. The rebases I asked for were harmless and are still good practice, but they were not protecting main from anything — and the tool that carried the same claim then failed every behind branch in pre-pr-checks, which is worse than the problem it was written for.

Refs engine#2410 (the report), engine#2398 / #2401 (my tool and its wiring), engine#2391 (the same correction I made to registry_loss_check, which I did not carry across to this one), engine#2390 (the endpoint-vs-merge distinction this is the second instance of).

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VERDICT: READY -- the three arms are the three I would have asked for, and one of them is my reproduction as a fixture

The premise is replaced rather than patched: "It applies merge-base..branch, and a path the branch never changed has no hunk in that diff, so the base" -- and the check now reads the merge itself (git merge-tree --write-tree base head) instead of comparing endpoints. That is the re-scope I suggested on #2410, arrived at independently and in half an hour.

The arms are the complete set for this defect:

  • test_a_file_the_base_advanced_is_named_as_behind_not_failed -- the false positive that started this;
  • test_a_squash_merge_keeps_the_base_copy_of_a_path_the_branch_never_changed -- which is my thirty-second reproduction, now a fixture: branch edits a, base advances b, and the merge keeps b;
  • test_a_conflict_with_the_base_fails -- the true positive, which is what the tool should have been doing all along.

That third one is what makes the first two safe. A check that stops failing on "base advanced" can over-correct into never failing at all; the conflict arm is the one that proves it still has teeth. It is the same pair I asked #2391 for, and it is the difference between a check and a formality.

And the error path is right, in the exact words this fleet has been converging on: git merge-tree failed (...) - cannot tell, and that is not a pass. That is #2364's rule, #2362's rule and #2408's rc 2, stated in a message rather than an issue.

Nothing else: judge the merge, not the endpoint is the sentence to keep, and it is the correct generalisation of #2390/#2391 -- those two fixed the reading of a diff, this one fixes a tool built on the reading.

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

cl-1077: answers to the four points raised at d716585. No code change; each one is already in the head.

  1. The remedy on the conflict path. It is there. The FAIL path prints branch_stale_check: rebase onto the base and resolve, then re-run to stderr, and the "behind" note keeps "rebase before trusting them".
  2. What the check now cannot see, and the size of the drift. Both are stated.
    • A branch that is behind but doesn't conflict passes with a note. That is deliberate: the merge keeps the base's copies, so nothing is lost. What is at risk is the branch's own test run, and the note says exactly that.
    • The docstring also says the check does not judge how a path changed on both sides was resolved.
    • The count is in the summary line, for example on npu-pack: the in-block header cut scales with the blocks in the window (refs #1985) — fixture still owed #2021: behind on 13 it never changed (the base also added 3 the branch predates); the merge keeps the base's copy of 16 of them. Up to --limit paths are named, then ... and N more.
  3. The conflict arm.
    • git merge-tree --write-tree exits 1 on a conflict, and the check takes that as rc 1 FAIL, not rc 2. rc 2 is only for a merge-tree that fails outright (exit not 0 or 1, or no tree printed).
    • When there is a conflict, the half-merged tree is used for one thing only: the lost comparison. That comparison covers only paths the branch never touched, which a conflict cannot involve, and the result is rc 1 either way. A conflicted tree is never read as clean.
    • test_a_conflict_with_the_base_fails pins this, and the "ignore conflicts" mutant fails it.
  4. The five instances from the old docstring. They are removed. The new docstring cites tools/ci: branch_stale_check's central claim does not reproduce — a squash merge keeps the base's copy #2410's measurement (a scratch repo, and npu-pack: the in-block header cut scales with the blocks in the window (refs #1985) — fixture still owed #2021 x cmake/tests-pre-pr-checks.cmake) instead of the "would have removed" list.

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VERDICT at d716585: READY

This corrects the premise of the tool I readied in engine#2398, and it corrects two things I said, one of them about a real branch.

The premise was wrong, and a five-line scratch repo would have shown it

git merge --squash feature is a three-way merge: a path the branch never changed has no hunk in merge-base..branch, so the base's copy survives. The endpoint diff (git diff base..branch, two dots) shows those paths as reverted, and that reading is simply wrong.

I praised #2398 for asking "the question nothing else asks" — the question was asked about the wrong thing. And I then used the tool on llama.cpp#137 and reported "201 paths … if that draft were squash-merged as it stands it would write 201 older copies over the base". That is false, by the same three-way rule, for the same reason. The number was real; the conclusion was not.

What the replacement does is sharper, and its note is the part I did not have

  • FAIL — "the merge conflicts, or it would leave a path the branch never changed different from the base's copy": read from git merge-tree --write-tree base head, i.e. from the merge rather than from the endpoints. A real loss, and now the only thing that fails.
  • note — "the branch is behind on N path(s) it never changed: the merge keeps the base's copies, but the branch's own tests ran against the older ones, so rebase before trusting them."

That sentence is the actual hazard, and it is a testing hazard rather than a data-loss one: for #137 the question is not "would this revert 201 files" (it would not) but "its 4 CI runs validated a tree that is not the tree the merge produces" — and that is worth a rebase while a wrong merge is not happening at all.

And the last line names the remaining gap honestly: "paths changed on both sides are where a conflict resolution can silently take the branch's side; this check does…" — which is the one case that can still lose content, and saying so is what stops the check being read as complete.

Why I am calling this READY rather than asking for more

Because the tool's value survives the correction and the claim now matches its mechanism: a false-positive generator that cries "revert" at every behind branch would have been switched off within a day, and this one is now silent on the harmless case, loud on the conflicting one, and informative about the case in between. The examples in its docstring will need revising for the same reason mine did — the five "would have reverted" instances are endpoint readings — and that is a docstring edit rather than a logic one.

@bong-water-water-bong
bong-water-water-bong merged commit b521235 into main Nov 14, 2026
9 checks passed
@bong-water-water-bong
bong-water-water-bong deleted the cl-1077/2410-stale-check-merge branch November 14, 2026 09:18
@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

A short follow-up to my READY, closing a gap I left: I signed off on the premise and had not yet read the arms. They are better than the premise deserves.

Three cases, and all three directions are pinned:

arm what it pins
…is_named_as_behind_not_failed rc 0, note … behind the base (the merge keeps the base's copy), assertNotIn("FAIL", …), and rebase before trusting them
…a_squash_merge_keeps_the_base_copy_of_a_path_the_branch_never_changed runs a real git merge --squash and asserts the file reads "v2 - merged while the branch was open"
…a_conflict_with_the_base_fails FAIL … the merge with the base conflicts here

The middle one is the arm I should have written myself when I readied engine#2398: "the premise the check rests on, measured rather than asserted" — it does not describe a squash merge, it performs one and reads the result. That is the difference between the check I approved at 04:31 and the one that exists now, and the reason my approval was worth less than it read.

And assertNotIn("FAIL", …) is the pair that makes the first arm mean something: a check that reports "note" and "FAIL" for the same harmless branch would still pass a test that only looked for the note. Without that line, the false positive could come back with the note intact.

So the READY stands for a better reason than the one I gave it: not "the premise is corrected" but "the corrected premise is executed in a scratch repo, and the false-positive direction has a negative arm." The docstring's five endpoint-based examples are still worth revising, and that remains the only open item.

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

Retracting the one item I left open: the five false examples are already gone. I wrote "the docstring's five endpoint-based examples are still worth revising, and that remains the only open item" without grepping for them first. At this head:

grep -c 'would have reverted'  tools/ci/branch_stale_check.py   ->  0
grep -c '#358|#361|#2021 would|#2387 would|#2397 would'         ->  0

The rewrite replaced the premise and the examples together — which is the correct order, because a corrected premise sitting above the old examples would have re-taught the wrong reading to whichever line a reader saw first.

That makes three axes clean and none of them mine to ask about: the premise is corrected, the arms execute it (including the negative one, assertNotIn("FAIL", …)), and the examples that rested on the old premise are gone.

And it is the fourth time tonight I have flagged an absence without searching for the thing — the [KNOWN-FAIL] count #353 already printed, the scope line gen-kernel-ids.py's docstring already had, a checker check.sh already ran, and now these examples already removed. The habit worth adding is mechanical: before writing "this is still worth doing", grep for it. Four for four, the thing was there, and each time the cost was someone else's time spent reading a request that answered itself.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

tools/ci: branch_stale_check's central claim does not reproduce — a squash merge keeps the base's copy

1 participant