How to Fix 'fatal: cannot delete branch used by worktree' in Git
Git is usually pretty good at protecting us from our own mistakes. When you try to delete a branch and get hit with the fatal: cannot delete branch 'xyz' used by worktree at '/path/to/folder' error, Git is essentially acting as a safeguard.
It is telling you: "I can't delete this branch because it is currently checked out and actively being used in another folder on your computer!"
Here is exactly why this happens and how to resolve it safely.
🌳 What is a Git Worktree?
To understand the error, you have to understand the feature. git worktree allows you to have multiple branches checked out at the exact same time in different physical folders on your hard drive, all sharing the same .git history.
Normally, Git stops you from deleting the branch you are currently on. With worktrees, Git also stops you from deleting a branch that is "currently on" in one of your other linked folders.
🛠️ The Fixes: 3 Ways to Solve It
Depending on whether you still need that other folder, here are the three ways to clear the error and delete your branch.
Method 1: The Clean Way (Remove the Worktree)
If you are completely done with that extra working directory and the branch, you should tell Git to safely dismantle the worktree first.
- List your worktrees to see exactly where the branch is checked out:
git worktree list
- Remove the worktree using the path provided in the list:
git worktree remove /path/to/the/worktree/folder
- Delete the branch normally:
git branch -d your-branch-name
Method 2: The "I Already Deleted the Folder" Fix (Prune)
This is the most common reason people get stuck. If you bypassed Git and just dragged the worktree folder to your computer's Trash/Recycle Bin, Git still thinks the worktree exists in its internal index.
You need to tell Git to clean up its dead links.
- Prune the dead worktrees:
git worktree prune
(This tells Git: "Hey, check if all the worktree folders actually exist. If they don't, forget about them.") 2. Force delete the branch:
git branch -D your-branch-name
Method 3: Keep the Folder, Change the Branch
If you want to keep the physical folder but just want to delete the branch that is currently active inside it, you simply need to switch branches in that specific folder.
- Navigate to the worktree path:
cd /path/to/the/worktree/folder
- Checkout a different branch (like
main):
git checkout main
- Go back to your main repo (or stay where you are) and delete the branch:
git branch -d your-branch-name
📊 Quick Command Summary
| Scenario | The Command You Need |
|---|---|
| Find the blocking folder | git worktree list |
| Delete the folder properly | git worktree remove <path> |
| Fix manually deleted folders | git worktree prune |
📚 Sources & Technical Refs
- [1.1] Git SCM Docs: git-worktree - Official documentation on managing multiple working trees.
- [2.1] StackOverflow: Cannot delete branch used by worktree - Community troubleshooting for corrupted worktree indexes.
