How to Remove a Git Worktree

git worktrees

Use git worktree remove <path> to delete a worktree. It removes the directory and git’s bookkeeping in one step. It does not delete the branch, so delete that separately once the work is merged.

git worktree remove ../myrepo-auth
git branch -d feature/auth

If you already deleted the folder with rm -rf, run git worktree prune to clear the leftover reference.

See what you have first

git worktree list
/Users/you/code/myrepo       eae19c2 [main]
/Users/you/code/myrepo-auth  eae19c2 [feature/auth]
/Users/you/code/myrepo-old   eae19c2 [fix/login] prunable

prunable means git still has a record of that worktree but the directory is gone. Those are the ones prune will clear.

You can name a worktree by any unambiguous trailing part of its path, so git worktree remove myrepo-auth works as well as the full path.

git worktree remove

git worktree remove ../myrepo-auth

Deletes the working directory and the administrative files git keeps in .git/worktrees/. Nothing else. The branch stays, its commits stay, and everything you committed there is still in the shared history.

Three refusals to expect.

Uncommitted or untracked files:

fatal: '../myrepo-auth' contains modified or untracked files, use --force to delete it

Read that as a prompt, not an obstacle. Check what’s in there before you force it, because untracked usually means an .env you copied in or work an agent hadn’t committed yet:

git -C ../myrepo-auth status
git worktree remove --force ../myrepo-auth

A locked worktree:

fatal: cannot remove a locked working tree, lock reason: on the usb drive
use 'remove -f -f' to override or unlock first

Unlock it properly:

git worktree unlock ../myrepo-auth
git worktree remove ../myrepo-auth

The main worktree:

fatal: '.' is a main working tree

The original clone is not removable through this command. That is the repo itself.

git worktree prune

prune clears records of worktrees whose directories no longer exist. It is the cleanup for rm -rf, for a folder that lived on a drive you unplugged, or for a directory something else deleted.

git worktree prune

See what it would do before it does it:

git worktree prune --dry-run -v
Removing worktrees/myrepo-old: gitdir file points to non-existent location

--expire <time> limits it to old entries, for example git worktree prune --expire 2.weeks.ago. Git also prunes on its own during garbage collection, governed by gc.worktreePruneExpire, so a stale entry eventually clears itself. “Eventually” is not much help mid-workflow, which is why you run it by hand.

prune never touches a live worktree, and it never deletes a branch.

What happens if you just delete the directory

Nothing breaks, but git keeps the record, and the record keeps the branch claimed. Until you prune:

  • The worktree shows as prunable in git worktree list.
  • The branch is still considered checked out. git branch -d on it fails with error: Cannot delete branch 'feature/auth' checked out at '/path/that/no/longer/exists'. See cannot delete branch used by worktree.
  • Reusing the same path fails: fatal: '../myrepo-auth' is a missing but already registered worktree.

One git worktree prune fixes all three.

Deleting the branch too

remove leaves the branch on purpose, because the branch is where the work is. Once it’s merged:

git worktree remove ../myrepo-auth
git branch -d feature/auth

-d refuses to delete an unmerged branch, which is the safety you want. -D forces it and throws the commits away. If you’re discarding an experiment on purpose, -D is correct. If you’re not sure, -d first and let it stop you.

Full teardown of one parallel task:

cd ~/code/myrepo
git merge feature/auth
git worktree remove ../myrepo-auth
git branch -d feature/auth
git worktree prune          # only needed if you deleted anything by hand
git worktree move ../myrepo-auth ../work/myrepo-auth   # relocate, keeping the link
git worktree repair                                     # fix links after moving folders manually
git worktree lock ../myrepo-usb --reason "external drive"
git worktree unlock ../myrepo-usb

repair is the one to remember if you moved the main repo or a worktree with Finder or mv. Run it from the main worktree and git reestablishes the connections.

Why this gets skipped

The commands are simple. The problem is that cleanup is the last step of a task, and the last step of a task is where attention runs out. Run parallel agent sessions for a week and you accumulate worktree folders whose branches are long since merged, plus branches that can’t be deleted because a directory that no longer exists still claims them.

Two habits fix most of it: put worktrees in one predictable place, and remove each one at merge time rather than “later”. More on both in the git worktree workflow.

crystl handles it structurally instead: an isolated session keeps its worktree in a managed directory, and closing it prompts you to merge, keep, or discard, so nothing is left claimed by a folder you forgot about.

Next