gh-worktree-gc

gh-worktree-gc

Prune merged and stale git worktrees safely — clean-only, so it can never lose work. The companion to gh-issue-lease: that one stops work stampedes, this one stops worktree bloat.

When a fleet of agents (or one busy human) spins up a worktree per task, they pile up fast — dozens of merged branches with dead worktrees hanging off them. gh-worktree-gc cleans them up without ever touching anything that could hold unsaved work.

npx gh-worktree-gc            # safe dry-run: shows the plan
npx gh-worktree-gc --apply    # execute

Zero runtime dependencies. One small file. gh is optional (used only to catch squash/rebase merges).

---

The safety invariant

Automation only ever removes CLEAN worktrees. A clean worktree has no uncommitted changes, so removing it cannot lose anything — the code is safely on a branch. Anything dirty or detached is BLOCKED — listed for you to handle by hand, never auto-removed (unless you pass --force and mean it).

Worktree state	Action on --apply
merged, clean	remove worktree + delete its local branch
stale (old), clean, unmerged	remove worktree, keep the branch (work is parked, not lost)
dirty / detached	BLOCKED — reported, never touched (needs --force)
protected (primary checkout, current worktree, bare, locked, /tmp)	never touched

---

Why gh matters here

"Merged" is detected two ways and OR'd together:

1. git ancestry (git branch --merged <base>, one batched call) — fast, local, no network.
2. merged PR head branches from gh pr list --state merged — when gh is available.

That second signal is the important one: a squash or rebase merge creates new commits on the base that are not ancestors of your branch, so a pure git check thinks the branch was never merged and leaves the worktree behind forever. Pulling the merged-PR list from GitHub catches exactly those. If gh isn't installed or authed, it silently falls back to ancestry-only (pass --no-gh to force that).

---

Install & use

npx gh-worktree-gc              # one-off, no install
npm i -D gh-worktree-gc         # or as a dev dependency

Requires git. gh (authenticated) is optional but recommended.

Flag	Default	Effect
(none)	—	Dry run. Print the plan, change nothing.
--apply	off	Execute the removals.
--merged-only	off	Ignore stale age; only prune merged worktrees.
--stale-days <n>	14	Age (days, by last commit) at which an unmerged clean worktree is "stale".
--base <ref>	remote default branch	What "merged" is measured against (auto-detects origin/HEAD).
--force	off	Also remove dirty/detached worktrees. Dangerous — can lose uncommitted work.
--no-gh	off	Skip PR-merge detection; use git ancestry only.
--no-fetch	off	Don't git fetch first.
--include-external	off	Don't protect /tmp, /private/tmp, /var/folders worktrees.
--json	off	Machine-readable plan.
--quiet	off	Suppress the report (for hooks/cron).

Programmatic API

import { classify, parseWorktrees, resolveDefaultBase } from "gh-worktree-gc";
// classify() is the pure decision function; the rest are the git helpers.

---

Automate it

Post-merge hook (opt-in) — GC after a local merge into the default branch:

mkdir -p .githooks
cp node_modules/gh-worktree-gc/hooks/post-merge .githooks/post-merge
chmod +x .githooks/post-merge
git config core.hooksPath .githooks
git config worktreeGc.enable true

Most merges happen on GitHub (which a local hook can't see), so the reliable catch-all is a periodic run — a cron, or after each git fetch:

gh-worktree-gc --apply --quiet

Because it uses gh to find merged PR branches, this reaps the squash/rebase-merged worktrees that a local hook would never notice.

---

Guarantees & edge cases

Case	Behaviour
Uncommitted changes in a worktree	BLOCKED — never removed without --force. The core safety guarantee.
Squash/rebase-merged branch	Detected via gh merged-PR list (git ancestry alone would miss it).
gh offline / not installed	Falls back to git-ancestry merge detection; still safe, just misses squash/rebase merges.
Current worktree / primary checkout	Protected — never touched.
Detached HEAD	BLOCKED (could hold commits not on any branch).
Stale but unmerged	Worktree removed, branch kept — parked work is never deleted.
Bare / locked worktrees	Protected.
Very large merged-PR history	gh pr list is capped at 300 by default; older merges fall back to ancestry.

License

MIT Mackenzie Robertson