Repository navigation
cleaner: merged branches and orphaned temp worktrees (#519) - #524
Conversation
Two jobs the old tools did that fork-cleaner had no rule for, so their leftovers piled up once it took over on the main dev host. Merged branches (worktrees rule, opt-in per repository with "mergedBranches": true, which needs "branches"): a local branch of a clone directly in the root goes when no worktree has it checked out, rebases or bisects it, its pull request merged a day or more ago, its tip is in the merged head or in GitHub's default branch, every commit it and its reflog name is on GitHub right now, and it was not used in the last day. The delete is git update-ref -d at the commit the last check judged, then its config section. One git step, no journal line. Orphaned worktrees in the temp folder: the tmp rule passes over a .git file whose git folder is gone (it holds no commit) and judges the entry as a plain folder by the pattern's days; every other git folder in it and every other refusal still holds. The worktrees and agent-scratch rules still keep an orphan. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review (independent, Opus)Reviewed at head No blocking findings. On the branch side I found no path that deletes a commit GitHub does not have. One orphan case can lose an unpushed commit (finding 1). It is narrow, and the old retention tool had the same behaviour, so I rated it SHOULD-FIX. The owner may want to escalate it. 1. SHOULD-FIX: an "orphan" whose repository was moved, not removed, still has a live admin entry, and deleting it can lose a detached-HEAD commit
Reproduced with the PR's own guard fixture:
Result: the run deletes Suggested fix, cheap and in proportion:
2. SHOULD-FIX: a deleted branch's commit is not logged, so there is no one-line undo
3. NIT: removing the config section after the ref delete is not tied to the same branch
There are two ways this goes wrong:
No commit is at risk. One mitigation: skip removing the section when 4. NIT: a symbolic-ref branch that points at a deleted branch is left dangling
State questions checked, no finding
|
Review (independent, Opus)Reviewed head
Verdict: no blocking findings. I found no case where a branch is deleted while a commit it or its reflog names is missing from GitHub. I also found no delete outside a configured root. One SHOULD-FIX and some NITs: SHOULD-FIX1. An "orphaned" worktree may only have its git folder out of reach. Its uncommitted files are then deleted after the pattern's days.
In all three cases the worktree's commits are safe, because they live in the main repository. Its unstaged and untracked edits are not: before this PR they kept the folder ( The PR says "the git folder that knew is gone". In these cases that is not true: the git folder is only out of reach. The age gate keeps the risk small, so this is not blocking. Cheap fix: treat a worktree as orphaned only when the deepest part of the NIT2. Killed between 3. In a reftable repository the 4. Two repositories with the same State question: what I checked and found sound
Verdict: no blocking findings (1 SHOULD-FIX, 3 NITs). |
…view) A temp worktree whose git folder is gone counts as orphaned only when the path is absolute, its deepest existing part is a real folder on the same filesystem and no mount point, no drive could be missing there (fstab, /mnt, /media, /run/media), and no repository near it or in a configured root still names it. Anything else is kept as "unknown parent". Merged branches: the log line names the deleted commit (was <oid>) so one line undoes it; the config section goes only while it is still the deleted branch's; a branch a symbolic ref points at is kept; the last check skips repositories of another GitHub repo in a shared root. README: the rule, the undo, and the reftable and shared-root limits. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Fixes #519
Once fork-cleaner took over on the main dev host, two jobs the old tools did stopped, and their leftovers piled up: local branches whose PR merged and whose worktree is gone, and temp folders that are git worktrees whose admin entry is gone ("orphaned").
What changes
1. Merged branches (part of the
worktreesrule, opt-in). A new per-repository key,"mergedBranches": true, turns this on. It needsbranchesset: only a branch that one of those patterns names is ever looked at. The rule looks at the local branches of each full clone directly inroot. A branch is deleted only when all of these hold:mergedHoursago.git ls-remote, or a listed PR head. Deleting a branch deletes its reflog, so a commit that was amended or reset away keeps the branch.usedHours(its reflog times and its ref file).KEEPfile, is not a must-keep path, is not reached through a link, and itsoriginis not on this machine.The delete runs
git update-ref -d refs/heads/<b> <oid>with the commit the last check judged. If the branch moved after that check, git removes nothing. The log line names that commit (... (was <oid>)), so one line undoes it:git fetch origin <oid> && git branch <b> <oid>. Thenbranch.<b>.*goes as withgit branch -d, but only while it is still the deleted branch's: the section is read before the delete and left alone when the branch exists again afterwards or the section changed meanwhile. A branch that a symbolic ref points at (an alias) is kept assymbolic ref names it. Two repositories of the machine file in onerootare each judged only against their own clones. The plan names each branchbranch <b> in <clone>(0 B). The compare ignores these lines (they are not paths), and the report counts them as 0 B.2. Orphaned worktrees in the temp folder. Before this change the
tmprule kept them forever. Now it passes over a.gitfile whose git folder is provably gone and judges the entry as a plain folder by the pattern's days. Provably gone means all of this holds:gitdir:path is absolute;st_dev) as the worktree, and not a mount point;/etc/fstabmount point that is not mounted now holds the path (an unreadable fstab counts as one), and it is not in/mnt,/mediaor/run/mediaunless a mounted drive below them holds it;.git/worktrees/*/gitdir, andworktrees/*/gitdirfor a bare repository) of that deepest folder, of each folder in it, and of each folder in a configured repository root are read, and none names this folder. A repository that was moved or renamed next to its old place is found, and with it the worktree's HEAD and commits.Anything else keeps the entry as
unknown parent(exit 0), with the reason, for example.../.git still names it: the repository was moved or renamed (git worktree repair there). Aftergit worktree repairthe worktree is judged as any worktree, unpushed commits and all. A folder that cannot be searched givescould not read(exit 1). Every other git folder inside (a clone, say) is still judged, and every other refusal still holds (KEEP, credential names, in use, mounts). The plan's reason saysorphaned worktree: its git folder ... is gone, so it holds no commit. Theworktreesandagent-scratchrules still keep an orphan, under its own name and with no error.General vs project
All of it is general: the code holds the rules, and the machine file holds only the patterns (
branches,tmp.patterns) and the switch (mergedBranches, default off). No project names, paths or days are in the code. To turn on the branch part, the dev host's machine file needs"mergedBranches": truenext to its existingbranches: ["work/*"]. This only works if the repository's clones are directly inroot. Branches of a clone outsiderootare never looked at, the same as the rest of the rule (only configured folders are judged).Fix round (reviews 7009744670, 7009774452)
(was <oid>), written before the delete, with the commit the last check read (not the plan's).symbolic ref names it).reftableclones (no ref or reflog files, so nousedHoursprotection; their reflog commits are still checked through git) and repositories sharing a root (theworktreesrule's last check still takes the first repository whose root holds the folder, as before this PR). Also: drives that only a systemd mount unit, autofs or a desktop mounts elsewhere are not seen; a repository moved far away (another filesystem, deeper down) is not seen.The state question
update-refis one ref transaction, and the clone stays, so a branch gets no journal line. The log line with(was <oid>)is written before the delete, so it is there even when the run is killed right after. If the run is killed after the ref went but before its reflog or config section went, the next run sees no branch and judges nothing; a leftoverbranch.<b>.*section is inherited by a later branch of that name that has none of its own (as git itself leaves it), documented in the README. The reflog left behind still counts for the clone's owngit log --reflogcheck, so it keeps more, not less (tested).half deletedand is never judged again.half deletedgets none of its branches judged (tested).mergedBranches(or with it set to false) looks at no branch, so updating the cleaner deletes nothing new (tested).mergedBrancheswithoutbranchesis a machine-file error (exit 2).originis not this GitHub repository is not looked at. Anoriginthat git rewrites to a folder on this machine keeps every branch.could not read(exit 1).unknown parentand kept; then it is judged as any worktree (tested with a moved repository, thengit worktree repair).gc.reflogExpireUnreachable, 30 days by default). After that, the branch becomes deletable.Tests
Fix round: the new tests fail on the old PR head (3fda252) and pass here: 6 orphan tests fail plus 1 error there (the reviewer's repro: detached commit, repository renamed, worktree aged; drive in fstab not mounted / mount point / unreadable fstab; empty drive place; broken link and relative gitdir; another filesystem; moved into a configured folder), and all 4 new branch tests (log line names the commit, config section tie, alias, two repositories in one folder). The true-orphan and pruned-entry tests delete on both. 19 more red-check mutations, one per new guard; each makes its test fail.
The tests of the first round fail on main and pass here:
worktrees.test.pyMergedBranches: 11 tests (each reason it keeps a branch, the default-branch tip, used, checked out, rebase or bisect, KEEP, origin here, GitHub down, last check, the update-ref guard, stopped half-way, half-deleted clone, old machine file).guard.test.pyGitFolders: 3 orphan tests, plus one that guards the guard's own answer.daily.test.py: the orphan test now expects the delete.The red checks gained 23 mutations, one per new refusal, and each makes its test fail.
Two notes on running these locally (WSL):
compress.test.py's red checks fail on unchanged main too here, because this machine has nozstd.scratch.test.pyis flaky on unchanged main here (two timing tests,changed after the last check). It passed on the final run.CI runs both.
The README has the new
Merged branchessection with its table, themergedBrancheskey row, the tmp paragraph on orphans, the "What it never deletes" exception, and the state lines. FORK_CHANGES.md is unchanged: it adds no T3 setting, and the cleaner has no row there.🤖 Generated with Claude Code