git worktree remove: How to Delete a Worktree
When you are finished with a linked worktree, use git worktree remove to delete the working directory and clean up the internal metadata that links it to the main repository. This is the recommended way to remove a worktree — it is safer than manually deleting the directory because Git checks for uncommitted changes and updates its bookkeeping automatically.
Try It: Cleaning Up with git worktree remove
Safe removal, dirty worktree errors, and --force — in the acme scenario
It's been a productive day on the acme project. You shipped a hotfix for the checkout crash, reviewed a teammate's auth refactor PR, and your payment feature is still right where you left it. But now you have three worktrees — time to learn how to clean them up properly with git worktree remove.
acme/ has the real .git/ directory. acme-hotfix/, acme-review/ each have a tiny .git file that points back — no duplicate history, no wasted disk.
Basic Usage
git worktree remove <worktree-path>The worktree-path is the directory of the linked worktree you want to delete. You can run this command from any worktree (including the main one) — it does not have to be run from inside the worktree being removed.
# List current worktrees to find the path
git worktree list
# Remove the worktree at ../acme-hotfix
git worktree remove ../acme-hotfixAfter running this command, the ../acme-hotfix directory is deleted and the branch it had checked out becomes available for checkout in other worktrees again.
Force Remove (--force)
By default, Git refuses to remove a worktree that contains modified tracked files, untracked files, or submodules. This safety check prevents accidental data loss. If you are sure you want to discard those changes, use the --force flag:
git worktree remove --force ../acme-hotfixA second level of force (--force --force) is required if the worktree is locked:
# Remove a locked worktree
git worktree remove --force --force ../acme-hotfixWarning: Force-removing a worktree permanently deletes any uncommitted changes in that directory. Commit or stash your work first if you need to keep it.
What Happens When You Remove a Worktree
Running git worktree remove performs the following steps:
- Safety check— Git inspects the worktree for modified tracked files and untracked files. If any are found, the command aborts unless
--forceis used. - Delete the working directory— The entire worktree directory (e.g.,
../acme-hotfix) is removed from disk, including its.gitfile. - Remove administrative data— Git deletes the corresponding directory under
.git/worktrees/in the main repository, which contains the worktree's HEAD, index, and other per-worktree state. - Unlock the branch— The branch that was checked out in the removed worktree is no longer marked as "in use," so it can be checked out in another worktree.
# Before removal — administrative data exists
ls .git/worktrees/
# acme-hotfix/
# After removal — it's gone
git worktree remove ../acme-hotfix
ls .git/worktrees/
# (empty or other worktrees)Clean Up with git worktree prune
If a worktree directory was deleted manually (with rm -rf or a file manager) instead of using git worktree remove, the administrative data in .git/worktrees/ is left behind. These stale entries can cause confusing errors like "branch is already checked out" even though the worktree no longer exists on disk.
Use git worktree prune to remove these orphaned entries:
# Preview what would be pruned (dry run)
git worktree prune --dry-run
# Actually prune stale entries
git worktree pruneFor more details on pruning, see the git worktree prune tutorial.
Best practice: Always use git worktree remove instead of deleting directories manually. This ensures both the files and the metadata are cleaned up in one step.
Common Errors
"contains modified or untracked files"
Git will not remove a dirty worktree by default. Either commit or stash your changes, or use --force:
$ git worktree remove ../acme-hotfix
fatal: '../acme-hotfix' contains modified or untracked files, use --force to delete it
# Option 1: commit your changes first
cd ../acme-hotfix && git add -A && git commit -m "WIP: save progress"
cd ../acme && git worktree remove ../acme-hotfix
# Option 2: force remove (discards changes)
git worktree remove --force ../acme-hotfix"cannot delete branch" after removal
Sometimes after removing a worktree, Git may still think the branch is checked out somewhere. This usually means stale administrative data needs to be pruned. Run git worktree prune to fix it. For a detailed walkthrough, see Troubleshooting: cannot delete branch.
$ git branch -d hotfix/checkout-crash
error: Cannot delete branch 'hotfix/checkout-crash' checked out at '/home/user/acme-hotfix'
# Fix: prune stale worktree data, then delete the branch
git worktree prune
git branch -d hotfix/checkout-crash"is not a working tree"
This error means the path you specified is not recognized as a linked worktree. Verify the correct path with git worktree list:
$ git worktree remove ../acme-old
fatal: '../acme-old' is not a working tree
# Check the actual paths
git worktree listFrequently Asked Questions
Is there a "git worktree delete" command?
No. Git does not have a git worktree delete command. The correct command is git worktree remove. Many people search for "git worktree delete" or "git remove worktree" — they all refer to the same operation described on this page.
What is the difference between remove and prune?
git worktree remove deletes a specific worktree directory and its metadata. git worktree prune cleans up metadata for worktrees whose directories have already been deleted by other means (e.g., rm -rf). Always prefer remove— use prune only to fix leftover metadata from manual deletions.
Can I remove the main worktree?
No. The main worktree (the original clone directory) cannot be removed with git worktree remove. Only linked worktrees created with git worktree add can be removed.
Do I need to delete the branch after removing the worktree?
git worktree remove only removes the worktree directory. It does not delete the branch. If you are done with the branch (e.g., it was merged), delete it separately with git branch -d branch-name.