How to Fix 'fatal: cannot delete branch used by worktree' in Git
Git provides safeguards to protect your active code branches from accidental deletion. When you try to delete a branch and receive the error:
fatal: cannot delete branch 'xyz' used by worktree at '/path/to/folder', Git is warning you that the branch is currently checked out and actively linked to another working directory on your machine.
Here is why this error occurs, how to resolve it using three different methods, and how to use the listing commands to manage your workspace.
What is a Git Worktree?
The git worktree feature allows you to have multiple branches checked out at the same time in different physical folders on your computer, all sharing a single .git history.
Normally, Git prevents you from deleting the branch you are currently on. With worktrees, Git extends this protection to any branch currently checked out in any of your other linked worktree folders.
How to Fix the Branch Deletion Error
Depending on whether you still need the folder associated with that worktree, choose one of the following methods to resolve the error.
Method 1: Remove the Worktree Safely
If you are done with the working directory and the branch, dismantle the worktree:
- List your active worktrees to locate the path:
git worktree list - Remove the worktree using the path shown in the list:
git worktree remove /path/to/worktree/folder - Delete the branch:
git branch -d your-branch-name
Method 2: Prune Manually Deleted Folders
If you bypassed Git commands and deleted the worktree directory using your file explorer or moved it to the trash, the internal .git index still thinks it exists. You need to clean up these stale links:
- Prune the dead worktrees:
(This tells Git to verify if the worktree paths exist on your hard drive, clearing out any missing directories).
git worktree prune - Force delete the branch:
git branch -D your-branch-name
Method 3: Keep the Folder, Switch the Active Branch
If you want to keep the directory but free up the branch so you can delete it, switch to a different branch in that worktree directory:
- Navigate to the worktree folder:
cd /path/to/worktree/folder - Checkout a different branch:
git checkout main - Return to your main repository directory and delete the branch:
git branch -d your-branch-name
Auditing and Listing Worktrees
To prevent getting lost in your directories, you can audit your linked branches at any time.
Reading git worktree list Output
git worktree list
The output displays lines containing:
/Users/dev/project a1b2c3d [main]
- Path: The absolute location of the worktree directory on your machine.
- Commit Hash: The current commit checked out in that folder.
- Branch: The name of the active branch inside the brackets.
Advanced Listing Flags
- Porcelain Mode (
--porcelain): Outputs data in key-value pairs, which is ideal for scripts and shell automation:git worktree list --porcelain - Verbose Mode (
-v): Shows additional details, such as whether a worktree is locked (which prevents it from being pruned or deleted):git worktree list -v
Command Reference
| Action | Command |
|---|---|
| Audit all active folders | git worktree list |
| Dismantle worktree directory | git worktree remove <path> |
| Clean up dead links | git worktree prune |
| Porcelain output | git worktree list --porcelain |
| Show locked status | git worktree list -v |
Sources
- [1] Git SCM Documentation: git-worktree manual page
- [2] StackOverflow Reference: Cannot delete branch used by worktree troubleshooting
- [3] Pro Git Book: Git Branching - Worktrees
