Skip to content

cleaner: merged branches and orphaned temp worktrees (#519) - #524

Merged
scuttletoby merged 6 commits into
mainfrom
work/519-cleaner-branches-orphans
Nov 19, 2026
Merged

scuttletoby merged 6 commits into
mainfrom
work/519-cleaner-branches-orphans

Conversation

@scuttletoby

@scuttletoby scuttletoby commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner

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 worktrees rule, opt-in). A new per-repository key, "mergedBranches": true, turns this on. It needs branches set: 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 in root. A branch is deleted only when all of these hold:

  • No worktree has it checked out, rebases it or bisects it. Such a branch is the worktree's: it is not listed, and goes in a later run than its worktree.
  • It has no open PR. It is not the default branch on GitHub, and no PR merges into it.
  • A merged PR from this repository (not a fork) has the branch, and merged at least mergedHours ago.
  • Its tip is in the merged PR's head, or in GitHub's default branch right now (for squash and rebase merges).
  • Every commit its tip and its reflog name is on GitHub right now. "On GitHub" means a branch or tag in 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.
  • It has not been used within usedHours (its reflog times and its ref file).
  • The clone has no top-level KEEP file, is not a must-keep path, is not reached through a link, and its origin is 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>. Then branch.<b>.* goes as with git 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 as symbolic ref names it. Two repositories of the machine file in one root are each judged only against their own clones. The plan names each branch branch <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 tmp rule kept them forever. Now it passes over a .git file 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:

  • the gitdir: path is absolute;
  • the deepest part of it that still exists is a real folder: no link on the way, no broken link, the same filesystem (st_dev) as the worktree, and not a mount point;
  • no drive could be missing there: no /etc/fstab mount point that is not mounted now holds the path (an unreadable fstab counts as one), and it is not in /mnt, /media or /run/media unless a mounted drive below them holds it;
  • no repository still names the worktree: the worktree lists (.git/worktrees/*/gitdir, and worktrees/*/gitdir for 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). After git worktree repair the worktree is judged as any worktree, unpushed commits and all. A folder that cannot be searched gives could 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 says orphaned worktree: its git folder ... is gone, so it holds no commit. The worktrees and agent-scratch rules 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": true next to its existing branches: ["work/*"]. This only works if the repository's clones are directly in root. Branches of a clone outside root are never looked at, the same as the rest of the rule (only configured folders are judged).

Fix round (reviews 7009744670, 7009774452)

  • Data loss (must fix): the orphan rule above. Before, a worktree whose repository was only moved, or on a drive not mounted right now, counted as orphaned and went by age with its detached commits. Now it is kept unless the orphan is provable. The HEAD rule holds by construction: a worktree whose admin entry is found anywhere is kept; normal worktrees are still checked for unpushed and detached commits.
  • Undo: each branch log line ends in (was <oid>), written before the delete, with the commit the last check read (not the plan's).
  • Config section: tied to the deleted branch (read before, compared after, left alone on any change).
  • Symbolic ref alias: kept (symbolic ref names it).
  • Two repositories in one root: the branch last check now skips a repository whose GitHub repo is not the clone's origin (before it judged the clone against the first repository in the folder).
  • README: the provable-orphan rule, the undo line, the config tie, the alias, and two limits: reftable clones (no ref or reflog files, so no usedHours protection; their reflog commits are still checked through git) and repositories sharing a root (the worktrees rule'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

  • It runs again: a deleted branch or folder is no longer a candidate. The tests run twice and the second run deletes nothing. A kept branch is listed again with its reason, and the run exits 0.
  • Two at once: the existing lock; the second run stops with "another run" and deletes nothing. A branch made anew, or its config changed, by someone else between the last check and the delete: update-ref refuses a moved branch, and the config section is left alone (tested).
  • It stops half-way:
    • Branch: update-ref is 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 leftover branch.<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 own git log --reflog check, so it keeps more, not less (tested).
    • Orphan folder: it goes through the existing descriptor delete and journal, so a half-removed folder is half deleted and is never judged again.
    • A clone that is itself half deleted gets none of its branches judged (tested).
  • Old or empty state:
    • A machine file without mergedBranches (or with it set to false) looks at no branch, so updating the cleaner deletes nothing new (tested).
    • mergedBranches without branches is a machine-file error (exit 2).
    • An older cleaner refuses the new key (exit 2), so install this one first, then add the key.
    • No matching branches: nothing is listed. No temp patterns: the tmp rule does nothing.
    • A clone whose origin is not this GitHub repository is not looked at. An origin that git rewrites to a folder on this machine keeps every branch.
    • GitHub or git down: the clone is kept as could not read (exit 1).
  • What it still cannot prove, and why it is accepted:
    • Orphan, foreign state: a drive or repository that comes back later is fine: until then the worktree is unknown parent and kept; then it is judged as any worktree (tested with a moved repository, then git worktree repair).
    • Orphan: git can no longer tell which files of an orphan were never committed (the git folder that knew is gone). The issue's criterion is "no unpushed commit can be found in it, older than the pattern's days". That is exactly what any plain folder the tmp pattern takes gets today.
    • Branch: a worktree that checks out the branch in the milliseconds between the last check and the delete will find it gone. Every commit is on GitHub, so nothing is lost.
  • Commits amended away: they keep their branch until git's own reflog expiry drops them (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.py MergedBranches: 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.py GitFolders: 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.

python3 -I -B fork-kit/cleaner/tests/worktrees.test.py   # OK (80)
python3 -I -B fork-kit/cleaner/tests/guard.test.py       # OK (66)
python3 -I -B fork-kit/cleaner/tests/engine.test.py      # OK (55)
python3 -I -B fork-kit/cleaner/tests/daily.test.py       # OK (19)
python3 -I -B fork-kit/cleaner/tests/report.test.py      # OK (35)
python3 -I -B fork-kit/cleaner/tests/install.test.py     # OK (20)
python3 -I -B fork-kit/cleaner/tests/scratch.test.py     # OK (51)
python3 -I -B fork-kit/cleaner/tests/compress.test.py    # OK (54)

Two notes on running these locally (WSL):

  • compress.test.py's red checks fail on unchanged main too here, because this machine has no zstd.
  • scratch.test.py is 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 branches section with its table, the mergedBranches key 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

scuttletoby and others added 3 commits November 19, 2026 12:16
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>
@scuttletoby

Copy link
Copy Markdown
Owner Author

Review (independent, Opus)

Reviewed at head 3fda2524e5: issue #519, the PR text, the diff, and fork-kit/cleaner (README, engine.py, guard.py, rules.py, facts.py). I ran the suites on a fresh clone (git 2.43): worktrees, guard, engine, daily, report and install all pass. With the PR's tests run against the merge-base lib/, worktrees, guard, daily and engine all fail, and each of the 23 new red-check mutations fails. So the tests do fail on the old code. I also ran throwaway temp-fixture probes. Nothing ran against a real repo or folder.

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

fork-kit/cleaner/lib/cleaner/guard.py:301, fork-kit/cleaner/lib/cleaner/facts.py:471, fork-kit/cleaner/README.md:314

orphaned_worktree returns a path when the gitdir: path is missing. That covers "the main repository was removed", but also "it was moved or renamed" and "its drive or mount is not there right now" (on WSL, for example, a /mnt/<x> path that is not mounted). In the moved case the admin entry still exists at the new location. It holds the worktree's HEAD, index and per-worktree reflog. So the claim "its commits, index and HEAD were in that git folder, so nothing in it is a commit that could still be lost" does not hold.

Reproduced with the PR's own guard fixture:

  1. Clone elsewhere/main-of-x. Make worktree tmp/agent-x, run git checkout --detach, and commit there without pushing.
  2. Run mv elsewhere/main-of-x elsewhere/main-of-x-moved. .git/worktrees/agent-x is still there.
  3. Age the worktree 30 days and use tmp pattern agent-*: 7.

Result: the run deletes tmp/agent-x with orphaned worktree: its git folder … is gone, so it holds no commit. Then git worktree prune in the moved repo, which gc also does on its own after gc.worktreePruneExpire, drops the admin entry. After that, git branch -a --contains <commit> is empty and fsck --unreachable --no-reflogs lists the commit. A worktree on a branch loses nothing, because the branch stays in the moved repo. The loss needs detached-HEAD work that was left untouched for the pattern's days.

Suggested fix, cheap and in proportion:

  • (a) Before passing over an orphan, look in the configured worktrees.repos[].root clones for a .git/worktrees/*/gitdir that names this folder's .git. If one does, keep the folder as orphaned worktree with "repository moved: git worktree repair".
  • (b) Keep it when the missing gitdir lies under a path that is a mount point or under /mnt/*.
  • (c) Either way, put "moved or unmounted repository" under "what it still cannot prove" in the README.

2. SHOULD-FIX: a deleted branch's commit is not logged, so there is no one-line undo

fork-kit/cleaner/lib/cleaner/rules.py:1260 (the why), together with delete_branch

git branch -d prints Deleted branch x (was abc1234). The cleaner's log line has only the PR number and the reason, not the oid. In the squash-merge path (its tip is in main on GitHub) the tip is not the PR head. Any remote branch was usually auto-deleted on merge, and the local reflog went with the branch. Scenario: T3 later resumes an old thread on work/a, or the owner wants the branch back. Today they have to search GitHub for the commit. With (was <oid>) in the log line, the undo is git fetch origin <oid> && git branch work/a <oid>. Use item.oid as the last check set it.

3. NIT: removing the config section after the ref delete is not tied to the same branch

fork-kit/cleaner/lib/cleaner/facts.py:631

There are two ways this goes wrong:

  • If something creates a new work/a with tracking in the gap after update-ref -d (for example git worktree add -b work/a … --track), --remove-section branch.work/a removes the new branch's upstream.
  • If the run is killed in that gap, the stale branch.work/a.* section stays. A later branch of the same name then silently inherits the old upstream.

No commit is at risk. One mitigation: skip removing the section when refs/heads/<b> exists again. The README could also mention the leftover section in the half-way paragraph; today it names only the reflog.

4. NIT: a symbolic-ref branch that points at a deleted branch is left dangling

local_branches correctly leaves symrefs out, and --no-deref is right. But a refs/heads/work/alias -> refs/heads/work/a ends up dangling, and that makes later for-each-ref output noisy. That case is rare; a one-line README mention would cover it.

State questions checked, no finding

  • Runs again, twice in a row: tested. Two runs at once: the engine's flock covers it. A second delete of the same ref fails safely: I confirmed that update-ref -d <ref> <oid> exits 1, not 128, both on a mismatch and on a missing ref (loose and packed), so it is Untouched.
  • Killed between deciding and deleting: recheck_branch re-derives everything, and update-ref compares against the oid judged. Killed between worktree remove and branch delete: these happen in different runs by design, and the branch then stands on its own checks.
  • Squash-merged name reused for new work: new commits are either not on GitHub (commits GitHub does not have) or not in the old head or main (commits not in the merged PR). A fresh, commit-less branch made from main is deletable only after usedHours, and loses nothing.
  • Unpushed commits, including ones reset or amended away: lonely runs over the tip plus the branch reflog, against live ls-remote refs plus PR heads. A missing reflog (core.logAllRefUpdates=false) gives git log -g exit 0 with empty output, so only the tip is checked, which is correct.
  • Worktree in use or with edits: its branch is in worktree list (prunable entries included), and rebase/am/bisect are covered. A worktree whose admin entry is gone cannot use the branch anyway.
  • Unreachable remote, or a repo with no default branch: ls-remote --symref gives no HEAD, which raises Unreadable, so the clone is kept as could not read (exit 1).
  • Symlinks or outside the root: clone_keeps checks realpath, branch paths are only lstated, and orphan deletes go through the existing tmp delete_path inside tmp_root.
  • Half-deleted clone: branch items carry the clone path, so the engine's halves filter drops them.

@scuttletoby

Copy link
Copy Markdown
Owner Author

Review (independent, Opus)

Reviewed head 3fda2524 against main edad3e5b: issue #519, the PR text, the full diff, and rules.py, guard.py, facts.py and engine.py around the new code. I ran all six suites on the PR head (all OK). I also ran the new tests against the old library: the orphan tests fail on their assertions (guard 6 failures, daily 1), and the MergedBranches tests error because the feature is not there. I checked these git behaviours in a throwaway repo (git 2.43):

  • update-ref --no-deref -d <ref> <wrong oid> exits 1 and removes nothing.
  • config --remove-section branch.work/a.b removes only that section, even with a dot in the name.
  • log -g on a branch with no reflog prints nothing and exits 0.
  • worktree list --porcelain still prints branch for a worktree whose folder is gone, so that branch is kept.

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-FIX

1. An "orphaned" worktree may only have its git folder out of reach. Its uncommitted files are then deleted after the pattern's days. fork-kit/cleaner/lib/cleaner/facts.py:465-470 (orphaned_worktree), used at guard.py:296-303.
orphaned_worktree calls a worktree orphaned when os.lstat(gitdir) gives ENOENT or ENOTDIR. That also happens when the git folder still exists but cannot be reached right now:

  • (a) The main repository is on a filesystem that is not mounted at the moment (a second disk, drvfs /mnt/c on WSL, NFS or autofs). The empty mount point gives ENOENT.
  • (b) The path to the git folder goes through a link that is broken for now.
  • (c) A worktree made with relative paths (worktree.useRelativePaths, git 2.48 and later) was moved with mv into the temp folder. Its admin entry and index are still in the main repository, but the relative gitdir: no longer resolves.

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 (git: uncommitted or untracked, or orphaned worktree). Now they go once nothing has changed for the pattern's days.

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 gitdir: path that still exists is a normal folder on the same filesystem as the temp root, and is not a mount point (facts.mounts() is already read). Keep a relative gitdir: that does not resolve as orphaned worktree. Or, at least, say in the README's tmp paragraph that an unreachable git folder counts as gone.

NIT

2. Killed between update-ref -d and config --remove-section, the run leaves the branch.<b>.* section behind for good. facts.py:622-634. The next run sees no branch, so nothing ever removes that section. If someone later makes a new branch with the same name (git branch work/a), it picks up the old remote and merge keys. git pull and git push then go to the old upstream, which may be deleted, without saying so. Nothing is lost.
Fix: remove sections with no matching branch while judging the clone, or note this in the README's state lines.

3. In a reftable repository the usedHours check sees nothing. rules.py branch_used. It reads .git/logs/refs/heads/<b> and the loose ref file. A reftable repository (--ref-format=reftable, git 2.45 and later) has neither, so the answer is always "unused". Commits are still safe, because reflog() and lonely() go through git. Only the 24 h grace period is lost. The worktree rule's logs/HEAD check has the same gap, which predates this PR.
Fix: when extensions.refStorage is set, read the times with git reflog show --date=unix instead, or keep the branch as could not read.

4. Two repositories with the same root: the second one's branches are never deleted. rules.py recheck_branch returns at the first repository whose root matches and has mergedBranches on. When the clone belongs to the second repository, same_repo fails, and the last check refuses with not a candidate. This is safe, but the branches stay for ever. recheck_tree has the same first-match pattern, which predates this PR. Use continue in place of return on that mismatch.

State question: what I checked and found sound

  • Runs again. A deleted branch is not listed again. Two runs at once are stopped by the flock in engine.Log. plan deletes nothing.
  • Killed between deciding and deleting. The last check re-reads everything after facts.forget(). item.oid comes from that check, and update-ref -d <oid> refuses if the branch moved (tested).
  • Killed between worktree remove and branch delete. In one run, a branch that a worktree had checked out is never planned. Items are sorted by label, so /… paths come before branch … labels. The branch only goes in a later run.
  • A half-deleted clone. halves filters out branch items by clone path (tested).
  • A squash-merged branch whose name was reused. New commits are in neither the old merged head nor main. They count as not on GitHub, or as an open PR, so the branch is kept. A branch reset to origin/main with no new commits can go once usedHours has passed. It then holds nothing that is not on GitHub.
  • Unpushed commits, or commits amended away. lonely() over the tip and the branch reflog, against what ls-remote returns plus the listed PR heads that exist locally. A PR head that is missing locally counts as not on GitHub, so the branch is kept.
  • A worktree that is in use, has uncommitted edits, or is rebasing or bisecting. It is listed by worktree list, including the prunable and locked kind, or caught by branch_busy.
  • A remote that cannot be reached, or no default branch. Unreadable, so the clone is kept as could not read (exit 1).
  • Links and roots. The clone is checked with realpath. The last check requires dirname == repo.root and tree_kind == 'clone'. A link that replaces the clone gives tree_kind None, so the branch is refused.
  • Temp orphans. A clone in the temp folder with linked worktrees is still refused (git: worktrees), so the cleaner never makes orphans itself. Files inside an orphan still count toward look.newest, and KEEP, credential names, in-use and mount checks still apply. The last check runs examine again, so a git folder that has come back is judged by git.

Verdict: no blocking findings (1 SHOULD-FIX, 3 NITs).

scuttletoby and others added 3 commits November 19, 2026 12:58
…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>
@scuttletoby
scuttletoby merged commit f4aad80 into main Nov 19, 2026
27 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

cleaner: merged branches and orphaned temp worktrees (left from the old tools)

1 participant