git worktree prune: Clean Up Stale Worktrees

The git worktree prune command removes administrative data for worktrees whose working directories no longer exist on disk. This is essential when worktree directories have been deleted manually instead of using git worktree remove.

What Does Prune Do?

Every linked worktree has a corresponding entry in .git/worktrees/ inside the main repository. This entry tracks the worktree's HEAD, index, and other per-worktree state. When you delete a worktree directory with rm -rf or a file manager, the administrative entry is left behind. Git still considers that worktree active, which causes problems:

The branch checked out in the deleted worktree cannot be checked out elsewhere ("already checked out" error).
git worktree list shows phantom entries pointing to directories that no longer exist.
git branch -d refuses to delete branches it thinks are still checked out.

Running git worktree prune scans for these orphaned entries and removes them, restoring Git to a clean state.

Basic Usage

git worktree prune

With no flags, the command silently removes all stale worktree entries. You can verify the result by running git worktree list before and after:

Before and after pruning

# Before: stale entry for a deleted directory
$ git worktree list
/home/user/project          abc1234 [main]
/home/user/project-old      def5678 [feature/old]   prunable

# Prune stale entries
$ git worktree prune

# After: stale entry is gone
$ git worktree list
/home/user/project          abc1234 [main]

Dry Run (--dry-run)

If you want to see what would be pruned without actually removing anything, use the --dry-run flag. Combine it with --verbose (or -v) for detailed output:

Preview what will be pruned

$ git worktree prune --dry-run --verbose
Removing worktrees/feature-old: gitdir file points to non-existing location /home/user/project-old/.git

This is a safe first step when you are unsure which entries are stale. The output tells you exactly which administrative directory will be removed and why Git considers it prunable.

Expire Flag (--expire)

By default, git worktree prune removes all stale entries regardless of age. The --expire flag limits pruning to entries older than a given time:

Expire-based pruning

# Only prune entries that have been stale for more than 7 days
git worktree prune --expire 7.days

# Only prune entries stale for more than 2 weeks
git worktree prune --expire 2.weeks

This is useful in automated scripts where a worktree directory might be temporarily unavailable (e.g., on an unmounted drive) and you do not want to prune it prematurely. Locked worktrees are never pruned regardless of the expire setting.

When to Use Prune

You typically need git worktree prune in these situations:

You deleted a worktree directory manually with rm -rf instead of git worktree remove.
A worktree was on a removable drive or network share that is no longer mounted.
You see "already checked out" errors for branches that should be available.
git worktree list shows entries pointing to non-existent directories.

Best practice: Always use git worktree remove to delete worktrees. This cleans up both the directory and the administrative data in one step, making prune unnecessary.

Automating Cleanup

Git automatically runs a lightweight prune during git worktree add, so stale entries are often cleaned up naturally as you create new worktrees. However, if you want to be proactive, you can add a prune step to your workflow:

Shell and Git aliases for cleanup

# Add to your .bashrc or .zshrc
alias gwtclean='git worktree prune --verbose && git worktree list'

# Or add it as a Git alias
git config --global alias.wt-clean '!git worktree prune -v && git worktree list'

CI pipeline example

# In a CI/CD pipeline, prune before creating worktrees
git worktree prune
git worktree add ../build-dir release/v2.0
# ... run build and tests ...
git worktree remove ../build-dir