Cleaning up stale worktrees safely

Worktrees are easy to create and easy to forget, which is a combination that produces a list of eleven directories, four of which no longer exist on disk and two of which contain work somebody meant to come back to. The cleanup is not difficult, but it has one irreversible step — removing a worktree with uncommitted changes discards files that were never in the object database, and no recovery technique brings those back. This recipe sorts the safe cases from the dangerous ones, within Git worktrees and parallel development.

When to use this approach

  • git worktree list returns more entries than you can account for.
  • Branches refuse to be checked out because a worktree you deleted still claims them.
  • Disk usage on a development machine has grown unexpectedly.
  • You are about to reclone and want to know what you would lose.
  • If you have two worktrees and you created both this morning, there is nothing here for you.

Step 1 — Inventory, including the ones that no longer exist 

# Human-readable, with the branch each one claims
git worktree list
# Machine-readable, which is what a cleanup script should parse
git worktree list --porcelain | awk '
  /^worktree /{p=$2}
  /^branch /{b=$2}
  /^detached/{b="(detached)"}
  /^prunable/{print "PRUNABLE " p " " b; p=b=""}
  /^$/{if (p) print "LIVE     " p " " b; p=b=""}'
# Verification: prunable entries are those whose directory is gone
git worktree list --porcelain | grep -c prunable
Three states a worktree can be inAn entry whose directory no longer exists is administrative debris and is safe to prune. A directory with a clean status has nothing outside the object database and can be removed. A directory with uncommitted changes holds files that exist nowhere else.What state is this worktree entry in?directory is gonePrunablesafe to prunepresent and cleanRemovablenothing uniqueuncommitted changesLook firstfiles exist nowhere elseonly the right-hand branch is irreversible, and it is the one people force

Step 2 — Prune the administrative leftovers

An entry whose directory has been deleted holds nothing. Pruning it releases the branch it was claiming.

git worktree prune --verbose --dry-run     # see what would go
git worktree prune --verbose               # then do it
# Verification: the branch that was locked is now checkoutable
git worktree list | wc -l
git switch fix/old-thing && git switch -

Pruning never touches a directory that exists, so it cannot lose anything. Run it first and the remaining list is shorter and easier to reason about.

Step 3 — Sort the live ones by what they would cost to lose 

# Uncommitted changes, per worktree
git worktree list --porcelain | awk '/^worktree /{print $2}' | while read -r wt; do
  n=$(git -C "$wt" status --porcelain 2>/dev/null | wc -l)
  printf '%3s changed files  %s\n' "$n" "$wt"
done
# Commits present in a worktree's branch but nowhere else
git worktree list --porcelain | awk '/^worktree /{print $2}' | while read -r wt; do
  b=$(git -C "$wt" symbolic-ref --quiet --short HEAD 2>/dev/null) || continue
  n=$(git rev-list --count "origin/main..$b" 2>/dev/null || echo 0)
  printf '%3s unmerged commits  %s (%s)\n' "$n" "$wt" "$b"
done

Two numbers, two different risks: uncommitted files are unrecoverable once removed, while unmerged commits survive in the object database and can be recovered through the reflog for a while — see recovering lost commits with git reflog.

What survives a worktree removalCommitted work lives in the shared object database and remains reachable through the branch or the reflog. Uncommitted changes and untracked files exist only in the worktree's directory, so removing it destroys them with no recovery path.Uncommitted changesCommitted workstored in the object databasenoyessurvives removalnoyesrecoverable afterwardsnothing to recoverreflog, for a whilewhat removal coststhe workonly the directorythis is the whole reason removal refuses by default when the tree is dirty

Step 4 — Remove the empty ones, commit the rest 

# A clean worktree removes without argument
git worktree remove ../app-review
# A dirty one refuses, which is correct — deal with it deliberately
git -C ../app-experiment status --short
git -C ../app-experiment stash push -u -m "wip from app-experiment"   # or commit it
git worktree remove ../app-experiment
# Verification: the stash survives in the shared object store
git stash list | head -3

SAFETY WARNING — git worktree remove --force deletes uncommitted and untracked files immediately. There is no reflog for content that was never committed and no undo. If a worktree refuses to be removed, that refusal is the last safeguard between you and losing someone’s afternoon; read the status output before overriding it.

Step 5 — Make the cleanup a habit rather than an event 

# A weekly one-liner: show worktrees whose branch is already merged
git worktree list --porcelain | awk '/^branch /{print $2}' | sed 's|refs/heads/||' |
while read -r b; do
  git merge-base --is-ancestor "$b" origin/main 2>/dev/null \
    && echo "merged, removable: $b"
done
# Verification: after the sweep, the list should be short enough to read at a glance
git worktree list | wc -l

A worktree whose branch is fully merged contains nothing unique by definition, so it is the safe half of the list. Running this weekly keeps the inventory small enough that the dangerous half stays visible.

The cleanup order that cannot lose workPrune first, because it only removes entries whose directories are already gone. Then remove the worktrees whose branches are merged. Only then look at the remainder individually, because that is where anything irreplaceable lives.Prunedeleted directoriesnothing to loseRemove mergedbranch is an ancestorStash or commitdirty worktreesReview the restone at a timeeach step shortens the list before the risky decisions have to be made

Validation checklist

Frequently Asked Questions

Why does a branch stay locked after I delete its directory?

Because Git tracks the association in administrative files inside the repository, not in the directory you deleted. git worktree prune clears those, which is the only step needed — there is nothing else to clean up.

Can I move a worktree instead of removing it?

Yes: git worktree move <path> <new-path> updates the bookkeeping along with the directory. Moving it by hand leaves Git pointing at the old location, which produces a prunable entry and a directory Git no longer knows about.

What about a worktree on a disk that is currently unplugged?

Lock it with git worktree lock --reason 'on the external drive'. Without the lock, a prune while the volume is absent removes the administrative entry, and reconnecting the disk leaves an orphaned directory that Git no longer associates with the repository.