Prune Damaged Worktrees

Pruning removes stale administrative records from .git/worktrees/ for worktrees whose physical directories have been deleted or unmounted. Unlike CLI git worktree prune, which deletes metadata unconditionally, WorktreeWise provides a Review-First Prune workflow that previews damaged entries and requires explicit confirmation.

Why Worktrees Need Pruning

Git stores metadata for linked worktrees in .git/worktrees/. A worktree record becomes orphaned when:

Folder Deleted Outside WorktreeWise: A developer deletes a worktree directory using terminal commands (rm -rf) or file explorer. Git still retains the registration and prevents that branch from being checked out elsewhere.
Directory Relocated Manually: Moving a worktree folder without git worktree move breaks the bidirectional pointer files.
Branch Replaced or Deleted: The branch associated with the worktree was deleted or force-rewritten elsewhere.
Temporary Drive Unmounted: An external drive or network share containing the worktree was disconnected.

The Review-First Prune Workflow

WorktreeWise performs an audit before pruning to ensure work is never lost unintentionally:

Prune review

Open Prune Review

Select the Broom icon (🧹) in the Worktrees panel toolbar, or press the keyboard shortcut:

Shortcut: Shift + P

If all registered worktrees are healthy and reachable, the Broom icon remains disabled.

Inspect Damaged Worktrees

WorktreeWise runs a non-destructive dry run (preview-prune-worktrees) and displays the review modal:

Worktree Name: Registered name of the worktree.
Path: The filesystem location where Git expected the worktree to reside.
Reason: The exact condition reported by Git (e.g. Directory does not exist or Missing gitdir reference).

Granular Selection

Select the checkboxes next to the worktrees you want to purge:

Check entries for directories that are permanently removed.
Leave entries unchecked if you plan to restore the directory or reconnect an external drive.

Confirm Cleanup

Select Prune Worktrees. WorktreeWise removes only the selected administrative references from .git/worktrees/:

Branches previously locked by missing worktrees become immediately available for checkout.
Healthy worktrees and source files are completely untouched.
The Worktree list and Overview dashboard update automatically.

Prune or Repair?

Situation	Recommended Action
The directory still exists on disk and contains work to preserve	Use Repair to restore pointer files.
The directory was permanently deleted and should be deregistered	Use Prune to clean up administrative records.

Repair a Damaged Worktree: Reconnect a moved worktree without pruning.
Worktree Overview Dashboard: Monitor worktrees flagged with the Needs prune status.
Lock a Git Worktree: Protect worktrees on temporary drives from automated pruning.