git-clean-worktrees

Clean Worktrees

Systematically find and remove git worktrees whose work is already on the main branch. The core problem this solves: worktrees created during feature work persist after the branch is merged, showing "modified" files that are actually already committed — creating confusion about what's merged and what isn't.

Why This Happens

Worktrees are created for isolation during feature work. When the branch gets merged (squash-merge, regular merge, or cherry-pick), the worktree doesn't disappear. It still has the branch checked out, and git status inside it shows modifications relative to the worktree's HEAD — but those changes are already on main. The worktree is stale but looks active.

Workflow

Step 1: List all worktrees

git worktree list

Identify the main worktree (the repo root) — it must never be removed. Everything else is a candidate for cleanup.

If there's only the main worktree, report "No secondary worktrees found" and stop.

Step 2: For each secondary worktree, determine if it's stale

Run these checks in order. A worktree is safe to remove if ANY of these conditions is true:

Check A: Branch is merged into main

git branch --merged main | grep -q <branch-name>

If the branch appears in --merged, all its commits are reachable from main. Safe to remove.

Check B: Squash-merged (branch not technically merged, but diff is empty)

Squash merges don't show up in --merged because git sees different commit hashes. Check if the branch's changes are already on main by comparing the trees:

git diff main...<branch-name> --stat

If this produces no output (empty diff), the branch's content is identical to main. Safe to remove.

Check C: Worktree has uncommitted changes that match main

If the worktree has uncommitted modifications, check whether those changes already exist on main:

# List uncommitted changes in the worktree
git -C <worktree-path> status --porcelain

# For each modified file, check if main already has those changes
git diff main -- <file-path>