Victor's room

Overview & Root Cause Summary: The error fatal: Cannot delete branch '<branch_name>' used by worktree at '<path>' occurs when attempting to delete a local branch using git branch -d or git branch -D while that branch is actively checked out in a linked Git worktree. Git enforces this safeguard to prevent orphaning the linked working directory. The issue also frequently arises when developers manually delete a worktree folder using rm -rf instead of the proper CLI command, leaving stale administrative metadata inside .git/worktrees/ that indefinitely locks the branch.

Understanding the Root Causes

• Active Linked Worktree Checkout: The target branch is currently active in another linked working directory created via git worktree add. Git forbids deleting or re-checking out a branch that is already assigned to a worktree.
• Stale Worktree Metadata After Manual Deletion: The worktree folder was deleted directly through a file manager or terminal rm -rf command without running git worktree remove, leaving orphaned administrative metadata inside .git/worktrees/.
• Locked Worktrees on Removable or Network Drives: Worktrees stored on unmounted external drives or network paths that Git flags as locked to prevent accidental corruption.
• Main Worktree Conflict: Attempting to delete the default primary branch (e.g., main or master) while checked out in the root repository.

Step 1: Quick Fix (Prune Stale Worktree Metadata & Delete Branch)

If you already deleted the worktree directory from your filesystem, prune Git’s internal worktree administrative records to release the branch lock.

# 1. View all registered worktrees and their associated paths and branches:
git worktree list

# 2. Prune administrative records for deleted worktree directories:
git worktree prune

# 3. Now delete the released local branch:
git branch -d <branch_name>

# (Or force delete if the branch contains unmerged commits):
# git branch -D <branch_name>

Step 2: Cleanly Remove an Existing Active Worktree

If the worktree directory still exists on disk, use the official Git CLI command to cleanly dismantle the working tree and delete the branch in sequence.

# 1. Safely remove the linked worktree and its working tree files:
git worktree remove <path_to_worktree>

# 2. If the worktree contains uncommitted changes you wish to discard, force removal:
git worktree remove --force <path_to_worktree>

# 3. Delete the associated branch:
git branch -d <branch_name>

Step 3: Unlocking Worktrees & Manual Administrative Purge

If the worktree was explicitly locked or its metadata directory became corrupted, unlock or manually purge the internal reference.

# Option A: Unlock a locked worktree before removal:
git worktree unlock <path_to_worktree>
git worktree remove <path_to_worktree>

# Option B: Repair broken worktree administrative links:
git worktree repair

# Option C: Manually remove orphaned worktree administrative records if pruning fails:
# Inspect metadata folders in .git/worktrees:
ls -la .git/worktrees/
rm -rf .git/worktrees/<worktree_folder_name>
git branch -D <branch_name>

Verification & Testing Steps

Confirm that the worktree registry is clean and that the target branch has been successfully removed from local tracking.

# 1. Verify that only valid active worktrees remain:
git worktree list

# 2. Confirm the deleted branch is no longer present:
git branch --list <branch_name>

# 3. Check repository status:
git status

Summary Comparison Table

Troubleshooting Scenario	Applied Command	Filesystem State	Recommended Scenario
Directory Already Deleted	git worktree prune	Clears internal .git/worktrees/	Worktree folder was manually deleted via rm -rf
Directory Still Exists	git worktree remove <path>	Deletes files & unregisters metadata	Clean, standard worktree decommissioning
Locked Worktree	git worktree unlock <path>	Releases administrative lock	Worktrees marked locked on external storage
Manual Metadata Purge	rm -rf .git/worktrees/<name>	Purges corrupt internal metadata	Severely corrupted or desynchronized worktree trees