You deleted a feature branch after merging its PR, but the linked worktree at ../project-feature is now in a broken state. Running git worktree list shows it as (bare) or with an (error) annotation, and cd ../project-feature && git status prints fatal: not a git repository. Or conversely, you cannot add a new worktree on that same branch path because Git reports fatal: 'feature/login' is already checked out at '../project-feature'. Worktrees store their metadata in .git/worktrees/<name>/, and that metadata does not automatically clean up when a branch is deleted or a directory is manually removed.
Common causes
Ordered by hit rate, highest first.
1. Worktree directory was manually deleted without git worktree remove
The developer ran rm -rf ../project-feature or the directory was removed by a disk-cleanup script. The .git/worktrees/project-feature/ metadata still exists in the main repo, causing Git to report a stale worktree.
How to spot it: git worktree list shows the path but the path does not exist on disk: ls -la ../project-feature returns “No such file or directory.”
2. Branch was deleted while the worktree was checked out
git branch -d feature/login or the remote branch was deleted and git fetch --prune removed the local tracking ref. The worktree is still on disk, but its branch no longer exists.
How to spot it: Inside the worktree directory, git branch shows * (HEAD detached at abc1234) or fatal: no such branch. Outside, git worktree list shows [detached HEAD].
3. Worktree was created on a remote-tracking branch
git worktree add ../project-feature origin/feature/login creates a detached HEAD worktree. When origin/feature/login disappears from the remote, git fetch --prune removes it, leaving the worktree in a permanently detached state.
How to spot it: cat .git/worktrees/<name>/HEAD contains a SHA rather than ref: refs/heads/....
4. Linked worktree .git file was corrupted or moved
Each worktree directory contains a .git file (not a directory) that points back to the main repo’s worktree metadata. If this file is corrupted, deleted, or if the main repo was moved to a different path, the worktree cannot find its parent.
How to spot it: cat ../project-feature/.git — it should contain gitdir: /path/to/main/.git/worktrees/project-feature. If the path is wrong or the file is missing, the worktree is broken.
5. Disk ran out of space during worktree creation
git worktree add partially ran — the metadata was created in .git/worktrees/ but the checkout never completed because the disk filled. The worktree path exists as an empty directory.
How to spot it: ls ../project-feature/ returns nothing or only .git. df -h shows the disk was near full at the time.
Shortest path to fix
Step 1: List worktrees and identify stale entries
git worktree list --porcelainEntries with a missing path or prunable annotation are stale.
Step 2: Prune stale worktree registrations automatically
git worktree prune --dry-run # show what would be removed
git worktree prune # actually prune stale entriesThis removes metadata for any worktree whose directory no longer exists on disk.
Step 3: Forcibly remove a locked or stuck worktree
# If pruning reports "locked: no reason given" or a manual lock message:
git worktree remove --force ../project-feature
# If the directory is already gone but the registration persists:
git worktree prune -vStep 4: Unlock a worktree that was locked deliberately
git worktree unlock ../project-feature
git worktree remove ../project-featureStep 5: Fix a detached worktree after branch deletion
cd ../project-feature
git switch -c feature/login-revived # create a new branch at the current SHA
# or: attach to an existing branch
git switch mainBack in the main repo:
git worktree list # should now show the branch name instead of detached HEADStep 6: Re-add a worktree on a clean path after removing the stale one
# After prune/remove:
git worktree add ../project-feature feature/login-v2Prevention
- Always remove worktrees with
git worktree remove <path>before deleting the directory or the branch. - Add
git worktree pruneto your project’s cleanup script or as a post-git fetch --prunehook. - Avoid creating worktrees directly on remote-tracking branches — instead, create a local branch first:
git switch -c feature/login origin/feature/loginthengit worktree add. - Name worktree directories to match branch names unambiguously so the relationship is obvious:
git worktree add ../project-login feature/login. - Set
worktree.guessRemote = truein your git config so thatgit worktree addautomatically creates a local tracking branch when a matching remote branch exists. - Document in your team’s development guide that deleting a branch requires removing the linked worktree first.
- Periodically audit worktrees:
git worktree listat the start of each sprint to remove stale entries.
FAQ
Q: Can I have two worktrees checked out on the same branch?
A: No. Git enforces that each branch is checked out in at most one location at a time to prevent divergent working trees. You will see fatal: 'feature/login' is already checked out at '<path>'.
Q: The worktree directory exists and has my changes, but git worktree list does not show it. How do I recover the changes?
A: If the .git file in the worktree is missing or broken, you can copy the uncommitted changes out manually (cp -r ../project-feature/src /tmp/rescue-src), then re-add the worktree cleanly and restore the files.
Q: How many worktrees can I have at once? A: There is no hard limit. Practically, each worktree holds its own index, HEAD, and checkout, consuming roughly the same disk space as the working tree. For large repos, 3-5 worktrees is manageable.
Q: git worktree add fails with “fatal: ‘/path’ is not an empty directory.” My changes are in there. What do I do?
A: The directory already exists. Either it is a stale worktree (use git worktree remove --force and re-add) or it contains manual files. Move those files out, remove the directory, then re-add the worktree.