worktree-reaper
/worktree-reaper
Zwalnia miejsce na dysku, usuwając worktree, których gałąź weszła do origin/main, domyślnie tylko w trybie podglądu.
- Autor
- langri-sha ↗
- Repozytorium
- skills ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 13.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 4
- Skrypty
- 2
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- 2 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: scripts/reap.sh, tests/run-tests.sh
Co robi i kiedy
Zwalnia miejsce na dysku, usuwając worktree, których gałąź weszła do origin/main, domyślnie tylko w trybie podglądu.
Argumenty
/worktree-reaper [--apply]
Oryginalny opis (EN)
Reclaims disk in a bare-repo worktree garden: reports what each worktree holds and removes only those whose branch has landed on origin/main, dry run by default, never touching main, dirty trees or worktrees in use. Use when asked to clean up or reap merged worktrees, or for a periodic disk-space pass. Not for creating worktrees (create-worktree).
Jak działa
- Layout It Expects
- Workflow
- What "Landed" Means
- Safety Model
- Options
- Edge Cases
- Resources
Podgląd SKILL.md
--- name: worktree-reaper description: >- Reclaims disk in a bare-repo worktree garden: reports what each worktree holds and removes only those whose branch has landed on origin/main, dry run by default, never touching main, dirty trees or worktrees in use. Use when asked to clean up or reap merged worktrees, or for a periodic disk-space pass. Not for creating worktrees (create-worktree). argument-hint: '[--apply]' metadata: author: langri-sha version: '1.3.1' --- # Worktree Reaper A periodic, disk-space-oriented cleanup pass over a bare-repo worktree garden. It classifies every worktree, measures what the removable ones hold, and removes only the ones whose work has demonstrably landed on `origin/main`. Dry run is the default and the mode meant for periodic use: it reads, measures, and reports, so it is safe to run on a schedule. Removal happens only under `--apply`, and only after a confirmation typed at the prompt. Never pipe a confirmation into `--apply` on the user's behalf: the prompt is the last human gate, so a scheduled or looped invocation stays in dry-run mode. Git objects live once in `.bare/`, so removing a worktree reclaims only its checked-out files: `node_modules`, build output, caches. `/create-worktree` grows the garden; this skill is what shrinks it. ## Layout It Expects ``` <repo>/ garden root <repo>/.bare/ bare repository — all objects and refs <repo>/.git file: "gitdir: ./.bare" <repo>/main/ worktree for the primary branch <repo>/<slug>/ feature worktrees, siblings of main/ ``` The reaper validates this layout before doing anything: `.bare/` must be a bare repository that is a direct child of the garden root, and `.git` must be a gitdir pointer to it. Anything else is refused outright rather than guessed at. ## Workflow ### 1. Run the Dry Report From anywhere inside the garden, where `<skill-dir>` is this skill's directory: ```bash <skill-dir>/scripts/reap.sh --fetch ``` `--fetch` refreshes `origin/main` first, which is the only thing the dry run writes and the only way the landed check sees recent merges. Without it the report leads with the age of the primary ref so stale verdicts are visible. ### 2. Read the Verdicts One line per worktree, `reap` first and sorted by size: ``` Worktree reaper — /home/user/src/my-app primary origin/main @ b17c2b19 (2026-07-27 02:47, 1d old) worktrees 65 pr evidence gh pr list on owner/my-app in-use scan 25 tmux window(s), 9 herdr tab(s), 3 hc terminal(s), process cwds mode dry run reap 929-reconcile-cache-state-drift 2.1 GiB merged via PR #930 (no unique commits, 1 empty commit(s) ignored) reap 905-fix-login-bug 1.8 GiB merged via PR #906 (patch-equivalent, 3 commit(s) already upstream, 1 empty commit(s) ignored) keep .bare - bare repository keep main - primary worktree (main) keep worktree-reaper-skill - current worktree skip pr-693-review - detached HEAD skip add-search-endpoint - 14 uncommitted or untracked change(s) skip fix-sidebar-layout-shift - not landed on origin/main (38 commit(s) with no upstream equivalent) skip main/.letta/worktrees/1073-wrapup-docs - agent-managed nested worktree, not a sibling of main/ 2 reap, 3 keep, 60 skip — 3.9 GiB reclaimable ``` Report the totals and the reap list to the user. If nothing is eligible, say so along with the dominant skip reasons — that is a useful answer, not a failure. ### 3. Apply, If Asked ```bash <skill-dir>/scripts/reap.sh --fetch --apply ``` Apply re-runs the dry report, then prompts: ``` Remove 2 worktree(s) and reclaim 3.9 GiB? Type y to confirm: ``` Before removing anything, apply re-reads `git worktree list`, re-scans for activity, and re-runs the **full classifier** on every candidate. A worktree that went dirty, got a tmux window, Herdr tab or hc terminal, gained a process, or stopped being landed while the report sat on screen is skipped with its fresh reason. ## What "Landed" Means PRs land here by rebase-merge, so the branch's commits are rewritten onto `main` with new SHAs. `git branch --merged` and `merge-base --is-ancestor` match almost nothing under that workflow and are not used. Instead, per worktree: `git cherry origin/main <branch>` must report **no unmatched commit that carries a change** — every commit unique to the branch either has a patch-equivalent commit already upstream, or alters nothing at all (see below). The evidence is reported per candidate, strongest first: | Evidence | Meaning | | ------------------- | ------------------------------------------------------------- | | `merged via PR #n` | `gh pr list --head <branch> --state merged` found a merged PR | | `patch-equivalent` | every unique commit has an upstream twin (the rebase case) | | `no unique commits` | the branch adds nothing over `origin/main` | PR evidence is corroboration, not the gate: it strengthens a verdict `git cherry` already reached, and its absence never makes a branch eligible. When `gh` is missing or `origin` is not a GitHub remote the header says so and the run continues offline. `git cherry` proves the commits appear in the primary's history, not that its current tree still holds them: a change that landed and was later reverted still reads as landed. Removal keeps the branch, so `git worktree add <path> <branch>` brings the worktree back. A commit that changes no files, such as `Retrigger CI`, has no patch for `git cherry` to match, and rebase-merge drops it, so it would hold its branch back forever. It cannot carry unlanded work, so it doesn't count; candidates say so in their evidence (`1 empty commit(s) ignored`). `--strict-commits` restores the commit-for-commit rule, which keeps any branch that ever needed a CI retrigger. ## Safety Model Never removed, under any flag: - the bare repository - the worktree on the configured `--primary` branch - the worktree on the repository's default branch, and anything named `main`, whatever `--primary` says — a comparison ref is not permission to delete the branch everything else is measured against - the worktree the reaper is invoked from - anything that is not a direct child of the garden root — nested agent worktrees under `.claude/worktrees/`, `main/.letta/worktrees/`, and `.bare/.claude/worktrees/` are all excluded by path - anything whose resolved path leaves the garden root, or that reaches its registered location through a symlink Skipped with a stated reason: - uncommitted or untracked files (ignored files like `node_modules` do not count — they are the point) - detached HEAD, locked worktrees, unresolvable branch refs - a worktree HEAD that disagrees with its branch tip - branches not confidently landed on the primary ref - worktrees in use: a tmux pane whose `pane_current_path` is inside them, a tmux window named exactly the slug, a Herdr TUI pane whose `cwd` is inside them, a Herdr TUI tab or workspace labelled exactly the slug, an hc terminal whose `cwd` is inside them, a Herdr app tab or space named exactly the slug, or any process whose cwd is inside them The header's `in-use scan` line names which of those detections actually ran, so a run with no tmux, no Herdr TUI server, no hc socket, or no `/proc` says so rather than quietly checking less than you think. Each multiplexer scan reaches one server: tmux's from `$TMUX` or its default socket, the Herdr TUI's from `HERDR_SOCKET_PATH` or its default session, hc's from `HC_SOCKET`, else the `socket` key in `~/.config/herdr-core/config.toml`, else `$XDG_RUNTIME_DIR/herdr-core/<HC_SESSION>.sock` with `default` as the session. Herdr clears `TMUX` in its panes, so a run inside Herdr nested in tmux sees the outer tmux only when that runs on the default socket. `hc ls` starts a core when nothing answers at that socket, a stale socket file left by a crashed core included, so the hc scan first checks that the socket exists and, with `ss`, that a process listens on it, and only then calls `hc`. A dry run therefore leaves no daemon behind. A missing socket reads as `no hc socket at <path>`; a core started under another runtime directory looks the same, with the path as the clue. A socket nothing listens on, no `ss`, a `socket` config value the scan cannot read, a failed `hc ls` and an unreadable reply all read as `hc UNAVAILABLE`, never as zero terminals. Mechanics: - removal is `git worktree remove` without `--force`, run from `main/`; a refusal from git is treated as a skip, not something to override - the script never deletes a path itself and never runs a recursive delete - branches are always kept; the run prints the `git branch -d` commands to run by hand if you want them gone - `git worktree prune` runs only under `--apply`, and only after at least one removal succeeded — never as a blanket first step ## Options | Option | Effect | | ------------------ | ----------------------------------------------------------- | | `--garden PATH` | Garden root to operate on (default: derived from cwd) | | `--primary REF` | Remote branch that defines "landed" (default `origin/main`) | | `--fetch` | Refresh the primary ref before classifying | | `--all-sizes` | Measure every worktree, not just reap candidates | | `--no-pr-evidence` | Skip the `gh pr list` lookup and stay fully offline | | `--strict-commits` | Require an upstream twin for every commit, even empty ones | | `--apply` | Remove candidates after a typed confirmation | Exit codes: `0` success, `1` usage or safety refusal, `2` a removal failed. ## Edge Cases - **Branch name differs from the directory name** — reported as `<slug> [<branch>]`; classification follows the branch. - **Several worktrees on one commit** — each is judged on its own branch; the shared commit is irrelevant. - **Stale worktree entries** (directory deleted by hand) — reported as missing and left registered until an apply run prunes them. - **`du` on a huge garden** — sizes are measured for candidates only; use `--all-sizes` when you want the full inventory and can wait. ## Resources - **`scripts/reap.sh`** — the reaper: inventory, classification, disk report, and the guarded apply path - **[`references/design.md`](references/design.md)** — why it works this way: where the space goes, what patch-equivalence misses, empty commits, and the fixture tests
Pliki w paczce (4)
- SKILL.md 11 KB
- references/design.md 4 KB
- scripts/reap.sh 25 KB
- tests/run-tests.sh 21 KB
Wersje
W bazie nie ma innych skilli o nazwie worktree-reaper.
Migawka bazy z 13.11.2026 · wersja paczki 857d742265f9 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100worktree-main-sync
Tworzy worktree i synchronizuje je z najnowszą gałęzią main z repozytorium zdalnego, także gdy jest za origin. - 81cleanup
Zwalnia miejsce na dysku, usuwając nieużywane worktree gita i foldery cache Next.js, z zachowaniem tych, z których korzystają sesje. - 86cleanup
Zwalnia miejsce na dysku w projekcie, usuwając nieużywane git worktrees i foldery cache Next.js, a oszczędzając worktrees używane przez sesje i cache działających serwerów. - 100clean-targets
Zwalnia miejsce na dysku, usuwając katalogi budowania cargo target/ w głównym checkoutcie i w każdym worktree repozytorium, pomijając te używane przez trwający build. - 100reap-worktrees
Sprawdza i usuwa pozostałe worktree po zmergowanych gałęziach lub zakończonych zgłoszeniach, zachowując aktywne i wstrzymane do wznowienia. - 100worktree
Tworzy worktree z origin/trunk w katalogu ~/worktrees.nosync i kopiuje node_modules, żeby zacząć pracę na gałęzi.