Git Worktree Add Error Fix

In this tutorial, you'll learn about Git Worktree Add Error Fix. We cover key concepts, practical examples, and best practices.

Git worktree lets you check out multiple branches in different directories at the same time. Errors occur when the worktree path already exists, the branch is already checked out elsewhere, or the branch name conflicts with the worktree directory.

The Problem

git worktree add ../feature-branch feature-branch

Error:

fatal: '../feature-branch' already exists

Or:

git worktree add ../new-feature

Error:

fatal: 'new-feature' is already checked out at '/other/path'

Wrong Approach

# WRONG — deleting the worktree directory manually
rm -rf ../feature-branch
git worktree add ../feature-branch feature-branch

Right Approach

# Remove the worktree with git worktree remove
git worktree remove ../feature-branch
git worktree add ../feature-branch feature-branch

Expected output:

Preparing worktree (checking out 'feature-branch')
HEAD is now at abc123... Commit message

Step-by-Step Fix

Step 1: List all worktrees

git worktree list

Expected output:

/home/user/main-repo         abc123 [main]
/home/user/other-worktree    def456 [feature-branch]

Step 2: Remove an existing worktree

git worktree remove /home/user/other-worktree

Step 3: Add a worktree with a new branch

git worktree add -b new-feature ../new-feature

Step 4: Add a worktree for an existing branch

git worktree add ../hotfix hotfix

Step 5: Add a worktree at a specific commit

git worktree add ../old-version abc123def

Step 6: Lock a worktree to prevent pruning

git worktree lock ../feature-branch

Step 7: Clean up stale worktree metadata

git worktree prune

Prevention Tips

• Use unique directory names when adding worktrees
• Check git worktree list before creating a new worktree
• Remove worktrees with git worktree remove, not rm -rf
• Lock worktrees you use frequently to prevent accidental pruning
• Use worktrees instead of git stash for context switching

Common Mistakes with worktree add

1. Non-exhaustive pattern matches that compile with warnings then crash at runtime
2. Misunderstanding that String is [Char] with poor performance for large text operations
3. Using foldl instead of foldl' causing stack overflow on large lists

These mistakes appear frequently in real-world GIT code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ