Skip to content
BSWEN
Blog

Common Git Worktree Mistakes and How to Fix Them

Cowrie
Cowrie
Dev @ Bswen

I tried to remove a git worktree and got an error. The command failed because my working directory wasn’t clean. This is one of the most common git worktree problems developers face.

Git worktrees are powerful for parallel development, but they come with their own set of pitfalls. Here are the five most common mistakes and how to fix each one.

Mistake 1: Removing a Worktree with Uncommitted Changes

I ran this command to remove a worktree:

Attempt to remove worktree
git worktree remove feature-branch

And got this error:

Error message
fatal: cannot remove a locked worktree

Or sometimes:

Alternative error message
fatal: 'feature-branch' contains modified or untracked files

Git protects you from losing work. The worktree has changes that aren’t committed.

How to Fix It

Option 1: Commit or stash your changes first

Commit changes
git add .
git commit -m "Save work in progress"
git worktree remove feature-branch

Option 2: Stash the changes

Stash and remove
git stash
git worktree remove feature-branch

Option 3: Force the removal (lose all changes)

Force remove (destructive)
git worktree remove -f feature-branch

Use -f only when you’re sure you don’t need the uncommitted work.

Mistake 2: Manually Deleting a Worktree Directory

I deleted a worktree directory manually:

Manual deletion (wrong approach)
rm -rf ../my-feature

Then I ran git worktree list and saw:

Stale reference in list
/Users/dev/main-project         abc1234 [main]
/Users/dev/my-feature           def5678 [feature]  <- This directory doesn't exist anymore!

The git worktree list still shows the old path. Git doesn’t know the directory is gone.

How to Fix It

Use the prune command to clean up stale references:

Prune stale worktrees
git worktree prune

Now check the list:

Clean worktree list
git worktree list
/Users/dev/main-project         abc1234 [main]

The stale reference is gone. You can also see what would be pruned first:

Dry run prune
git worktree prune --dry-run

Mistake 3: Moving the Main Repository Breaks Worktree Paths

I moved my main repository to a different location:

Moving the repository
mv ~/projects/my-app ~/workspace/my-app

Then my worktrees stopped working:

Broken worktree error
fatal: /Users/dev/workspace/my-app is not a git repository

Worktrees store absolute paths. Moving the main repository breaks these references.

How to Fix It

Git 2.17+ includes a repair command:

Repair worktree paths
git worktree repair

This command updates all the path references automatically.

If you’re on an older Git version, you’ll need to remove and recreate the worktrees:

Manual repair on old Git
git worktree remove broken-worktree
git worktree add ../new-worktree branch-name

Check your Git version:

Check Git version
git --version

Mistake 4: Accidentally Operating on the Wrong Worktree

I wanted to run a destructive operation on my main worktree. But I was in a feature worktree directory. I almost deleted files I didn’t mean to.

Git worktrees don’t have protection against accidental operations by default.

How to Fix It

Lock a worktree to prevent accidental removal:

Lock a worktree
git worktree lock feature-worktree

Now if someone tries to remove it:

Lock prevents removal
git worktree remove feature-worktree
fatal: cannot remove a locked worktree

Unlock when you’re ready to remove it:

Unlock before removal
git worktree unlock feature-worktree
git worktree remove feature-worktree

You can also add a reason for the lock:

Lock with reason
git worktree lock --reason "Working on critical feature, do not remove" feature-worktree

Check what’s locked:

List worktrees with details
git worktree list --porcelain

Mistake 5: Using the Same Path Name as a Branch Name

I tried to create a worktree with the same path as an existing branch:

Path name conflict
git worktree add feature-auth feature-auth

Got this error:

Already exists error
fatal: 'feature-auth' already exists

Git thinks you’re trying to create a worktree at the existing branch location. The path and branch name conflict.

How to Fix It

Use a different path name:

Use different path name
git worktree add ../auth-work feature-auth

Or specify the full path explicitly:

Explicit path and branch
git worktree add -b feature-auth ../auth-feature main

The pattern is:

Worktree add syntax
git worktree add <path> <branch>

Make the path different from the branch name to avoid confusion.

Quick Reference Table

ErrorCauseFix
”contains modified files”Uncommitted changesCommit, stash, or use -f
”already exists”Path conflictUse different path name
Stale referencesManual deletiongit worktree prune
Broken pathsMoved repogit worktree repair
Accidental opsNo protectiongit worktree lock

Summary

Git worktree errors are frustrating but fixable. The five most common mistakes are:

  1. Removing with uncommitted changes - Commit, stash, or force
  2. Manually deleting directories - Use prune to clean references
  3. Moving the main repository - Run repair to fix paths
  4. Accidental operations - Use lock for protection
  5. Path name conflicts - Use different names for paths and branches

Remember the key commands: remove -f for forced removal, prune for cleanup, repair for path fixes, and lock/unlock for protection.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: