gh-cskiro-claudex-devops-tools/skills/git-worktree-setup/data/troubleshooting.md

Git Worktree Troubleshooting Guide

Comprehensive troubleshooting for common git worktree issues, errors, and edge cases.

Table of Contents

1. Creation Errors
2. Permission Issues
3. Corruption and Repair
4. Branch Conflicts
5. Directory Issues
6. Performance Problems
7. Dependency Installation
8. Git Operations
9. Cleanup Issues
10. Advanced Debugging

---

Creation Errors

Error: "fatal: invalid reference"

Full Error:

fatal: invalid reference: feature-x

Cause: Branch doesn't exist (typo or branch not created yet).

Solutions:

1. Create new branch:

   git worktree add ../myapp-feature-x -b feature-x
   

2. Check branch name:

   git branch -a  # List all branches
   git branch | grep feature  # Search for branch
   

3. Track remote branch:

   git worktree add ../myapp-feature-x -b feature-x --track origin/feature-x
   

---

Error: "fatal: 'path' already exists"

Full Error:

fatal: '../myapp-feature-x' already exists

Cause: Directory already exists at target path.

Solutions:

1. Remove directory:

   rm -rf ../myapp-feature-x
   git worktree add ../myapp-feature-x -b feature-x
   

2. Use different location:

   git worktree add ../myapp-feature-x-v2 -b feature-x
   

3. Check if it's a forgotten worktree:

   git worktree list  # If not listed, safe to remove
   

---

Error: "fatal: 'branch' is already checked out"

Full Error:

fatal: 'feature-x' is already checked out at '/Users/connor/myapp-feature-x'

Cause: Branch is already checked out in another worktree.

Solutions:

1. Navigate to existing worktree:

   git worktree list  # Find existing worktree
   cd /path/to/existing/worktree
   

2. Remove existing worktree:

   git worktree remove /path/to/existing/worktree
   # Then create new one
   git worktree add ../myapp-feature-x feature-x
   

3. Use different branch:

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

---

Error: "fatal: not a git repository"

Full Error:

fatal: not a git repository (or any of the parent directories): .git

Cause: Not in a git repository.

Solutions:

1. Navigate to repository:

   cd /path/to/your/git/repo
   git worktree add ../worktree-name -b branch-name
   

2. Verify git repository:

   git status  # Should not error
   ls -la .git  # Should exist
   

3. Initialize if needed:

   git init  # Only if starting new repo
   

---

Permission Issues

Error: "Permission denied"

Full Error:

error: unable to create file: Permission denied

Cause: Insufficient permissions to create worktree directory.

Solutions:

1. Check parent directory permissions:

   ls -ld $(dirname /path/to/worktree)
   

2. Fix permissions:

   chmod 755 /path/to/parent
   

3. Use location you own:

   git worktree add ~/worktrees/myapp-feature-x -b feature-x
   

4. Check disk quota:

   df -h  # Check disk space
   quota -s  # Check user quota (if applicable)
   

---

Error: "Operation not permitted"

Cause: macOS security restrictions or readonly filesystem.

Solutions:

1. Grant Full Disk Access:

   • System Preferences → Security & Privacy → Privacy
   • Full Disk Access → Add Terminal/IDE

2. Check filesystem mount:

   mount | grep "$(pwd)"
   # If shows 'ro' (readonly), remount:
   # sudo mount -uw /
   

3. Use different location:

   # Use home directory (always writable)
   git worktree add ~/worktrees/myapp-feature-x -b feature-x
   

---

Corruption and Repair

Error: "Worktree path doesn't exist but listed"

Symptoms:

git worktree list
# Shows: /path/to/missing/worktree abc123 [branch]
# But: ls /path/to/missing/worktree
# No such file or directory

Cause: Worktree directory manually deleted without git worktree remove.

Solutions:

1. Prune orphaned references:

   git worktree prune
   git worktree list  # Verify removed
   

2. Force remove:

   git worktree remove --force /path/to/missing/worktree
   

3. Manual cleanup:

   # Check administrative files
   ls .git/worktrees/
   # Remove specific worktree directory
   rm -rf .git/worktrees/branch-name
   git worktree prune
   

---

Error: "Corrupt worktree"

Symptoms:

• Can't checkout files
• Git commands fail in worktree
• Missing .git file in worktree

Solutions:

1. Repair worktree:

   git worktree repair
   

2. Check .git file:

   cat worktree-path/.git
   # Should show: gitdir: /path/to/main/.git/worktrees/branch
   

3. Recreate .git file:

   # If corrupt, recreate
   echo "gitdir: $(git rev-parse --git-dir)/worktrees/branch-name" > worktree-path/.git
   

4. Last resort - recreate worktree:

   # Backup any changes
   cp -r worktree-path worktree-path-backup
   
   # Remove and recreate
   git worktree remove --force worktree-path
   git worktree add worktree-path branch-name
   
   # Restore changes
   cp worktree-path-backup/* worktree-path/
   

---

Branch Conflicts

Error: "Cannot delete branch checked out in worktree"

Full Error:

error: Cannot delete branch 'feature-x' checked out at '/path/to/worktree'

Cause: Trying to delete branch that's checked out in a worktree.

Solutions:

1. Remove worktree first:

   git worktree remove /path/to/worktree
   git branch -d feature-x
   

2. Force delete (if sure):

   # This will remove worktree administrative files
   git worktree remove --force /path/to/worktree
   git branch -D feature-x
   

3. Switch branch in worktree:

   cd /path/to/worktree
   git checkout different-branch
   # Now can delete feature-x in main repo
   

---

Error: "Reference is not a tree"

Full Error:

fatal: reference is not a tree: abc123

Cause: Commit reference doesn't exist or is corrupted.

Solutions:

1. Fetch latest:

   git fetch --all
   git worktree add ../worktree branch-name
   

2. Use specific commit:

   git worktree add ../worktree commit-hash
   

3. Check object exists:

   git cat-file -t abc123  # Should show 'commit'
   git fsck  # Check repository health
   

---

Directory Issues

Error: "Disk quota exceeded"

Full Error:

error: unable to create file: Disk quota exceeded

Cause: Not enough disk space or quota exceeded.

Solutions:

1. Check disk space:

   df -h
   du -sh /path/to/worktrees
   

2. Clean up old worktrees:

   git worktree list
   git worktree remove /path/to/old/worktree
   

3. Clean build artifacts:

   cd worktree
   rm -rf node_modules dist build .next
   npm install  # Reinstall only what's needed
   

4. Use different partition:

   git worktree add /other/partition/worktree -b branch
   

---

Error: "Worktree directory not empty"

Symptoms: Directory exists with files but not a git worktree.

Solutions:

1. Remove conflicting directory:

   # Backup if needed
   mv /path/to/directory /path/to/directory-backup
   
   # Create worktree
   git worktree add /path/to/directory -b branch
   

2. Merge contents:

   # Create worktree elsewhere
   git worktree add /temp/location -b branch
   
   # Copy existing files
   cp -r /path/to/directory/* /temp/location/
   
   # Move worktree
   git worktree move /temp/location /path/to/directory
   

---

Performance Problems

Problem: "Slow git operations in worktree"

Symptoms:

• git status takes 10+ seconds
• git checkout is very slow
• High CPU usage

Solutions:

1. Check filesystem performance:

   # Test read speed
   time cat large-file.txt > /dev/null
   
   # Test write speed
   time dd if=/dev/zero of=test.img bs=1M count=1024
   

2. Disable status optimizations:

   # If on network drive
   git config core.fsmonitor false
   git config core.untrackedCache false
   

3. Use sparse checkout:

   git sparse-checkout init --cone
   git sparse-checkout set src/ tests/
   

4. Move to local disk:

   # Network drives are slow
   git worktree add ~/local-worktrees/feature-x -b feature-x
   

---

Problem: "High disk usage"

Symptoms:

• Each worktree uses 1GB+
• Running out of disk space

Solutions:

1. Use pnpm:

   npm install -g pnpm
   # pnpm uses content-addressable storage
   # Saves ~70% disk space for node_modules
   

2. Share node_modules:

   # In main repo
   pnpm install
   
   # In worktree
   pnpm install --prefer-offline
   # Uses shared cache
   

3. Clean build artifacts:

   # Add to package.json
   "scripts": {
     "clean": "rm -rf dist build .next coverage"
   }
   
   # Run before removing worktree
   npm run clean
   

4. Limit worktrees:

   # Keep only 3-4 active worktrees
   # Remove old ones regularly
   

---

Dependency Installation

Error: "npm install fails in worktree"

Symptoms:

npm ERR! code ENOENT
npm ERR! syscall open
npm ERR! path /path/to/worktree/package.json

Solutions:

1. Verify package.json exists:

   ls -la worktree-path/package.json
   

2. Check file permissions:

   chmod 644 worktree-path/package.json
   

3. Copy from main repo:

   cp main-repo/package.json worktree-path/
   cp main-repo/package-lock.json worktree-path/
   

4. Reinstall:

   cd worktree-path
   rm -rf node_modules package-lock.json
   npm install
   

---

Error: "Lockfile conflict"

Symptoms:

npm ERR! Cannot read property 'match' of undefined

Cause: Lockfile from different package manager or corrupted.

Solutions:

1. Match package manager:

   # Check main repo
   ls main-repo/*lock*
   
   # If pnpm-lock.yaml:
   pnpm install
   
   # If yarn.lock:
   yarn install
   
   # If package-lock.json:
   npm install
   

2. Remove and regenerate:

   rm package-lock.json
   npm install  # Creates fresh lockfile
   

3. Copy lockfile from main:

   cp main-repo/package-lock.json worktree/
   npm ci  # Clean install from lockfile
   

---

Git Operations

Error: "Cannot merge in worktree"

Symptoms:

error: Your local changes would be overwritten by merge

Solutions:

1. Commit or stash changes:

   git add .
   git commit -m "WIP: save changes"
   # Or:
   git stash push -m "WIP before merge"
   

2. Merge with strategy:

   git merge --no-commit --no-ff branch-name
   # Review changes, then commit
   

3. Rebase instead:

   git rebase main
   # Replay commits on top of main
   

---

Error: "Detached HEAD in worktree"

Symptoms:

You are in 'detached HEAD' state

Cause: Checked out specific commit instead of branch.

Solutions:

1. Create branch from current state:

   git checkout -b new-branch-name
   

2. Checkout existing branch:

   git checkout branch-name
   

3. Return to main branch:

   git checkout main
   

---

Cleanup Issues

Error: "Cannot remove worktree - dirty"

Full Error:

error: repository is dirty, please commit or stash your changes

Cause: Worktree has uncommitted changes.

Solutions:

1. Commit changes:

   cd worktree-path
   git add .
   git commit -m "Final changes before removal"
   git push  # Push if needed
   
   # Now remove
   git worktree remove $(pwd)
   

2. Stash changes:

   cd worktree-path
   git stash push -m "Saved before worktree removal"
   # Stash is available in main repo
   
   git worktree remove $(pwd)
   

3. Force remove (lose changes):

   git worktree remove --force worktree-path
   # ⚠️ WARNING: All uncommitted changes lost!
   

---

Error: "Worktree locked"

Full Error:

error: 'worktree-path' is locked; use 'unlock' to override, or 'remove --force'

Cause: Worktree manually locked to prevent removal.

Solutions:

1. Unlock and remove:

   git worktree unlock worktree-path
   git worktree remove worktree-path
   

2. Force remove:

   git worktree remove --force worktree-path
   

3. Check why locked:

   cat .git/worktrees/branch-name/locked
   # Shows reason for lock
   

---

Advanced Debugging

Diagnostic Commands

Check worktree health:

# List all worktrees
git worktree list

# Check git database
git fsck

# Verify repository integrity
git status
git branch -vv

# Check worktree administrative files
ls -la .git/worktrees/

# Detailed worktree info
git worktree list --porcelain

Debug specific worktree:

cd worktree-path

# Check git configuration
git config --list --local

# Check remote tracking
git branch -vv

# Check what's tracked
git ls-files

# Check for corruption
git fsck --full

---

Enable Debug Logging

Git verbose mode:

GIT_TRACE=1 git worktree add ../debug -b debug
# Shows all git commands executed

Trace specific operations:

# Trace file operations
GIT_TRACE_PACK_ACCESS=1 git status

# Trace setup
GIT_TRACE_SETUP=1 git worktree list

# Trace performance
GIT_TRACE_PERFORMANCE=1 git status

---

Recovery Procedures

Recover deleted worktree:

# If worktree removed but branch still exists
git worktree add ../recovered branch-name

# If branch deleted too
git reflog  # Find commit
git worktree add ../recovered commit-hash
git checkout -b branch-name

Recover from backup:

# If you have time machine / backup
cp -r /backup/path/to/worktree /current/path/

# Repair git references
git worktree repair

Nuclear option - start fresh:

# Backup important changes
cp -r worktree-path/src ~/backup/

# Remove all worktrees
git worktree list | grep -v "$(git rev-parse --show-toplevel)" | \
  awk '{print $1}' | xargs -I{} git worktree remove --force {}

# Clean up administrative files
git worktree prune

# Recreate from scratch
git worktree add ../fresh-start branch-name

# Restore backed up changes
cp -r ~/backup/* ../fresh-start/src/

---

Getting Help

Before Asking for Help

Collect diagnostic information:

#!/bin/bash
# worktree-diagnostics.sh

echo "=== Git Version ==="
git --version

echo -e "\n=== Worktree List ==="
git worktree list

echo -e "\n=== Repository Status ==="
git status

echo -e "\n=== Branch Info ==="
git branch -vv

echo -e "\n=== Remote Info ==="
git remote -v

echo -e "\n=== Worktree Admin Files ==="
ls -la .git/worktrees/

echo -e "\n=== Disk Space ==="
df -h .

echo -e "\n=== File Permissions ==="
ls -ld .git
ls -ld .git/worktrees/

# Save to file
# ./worktree-diagnostics.sh > diagnostics.txt

Common Support Channels

• Git Documentation: git help worktree
• GitHub Issues: Check git/git repository
• Stack Overflow: Tag: git-worktree
• Git Mailing List: git@vger.kernel.org

---

Quick Reference

Most Common Issues

1. Directory exists: rm -rf path && git worktree add path branch
2. Branch checked out: git worktree remove old-path && git worktree add new-path branch
3. Orphaned worktree: git worktree prune
4. Permission denied: chmod 755 parent-dir
5. Can't remove (dirty): git stash && git worktree remove path

Essential Commands

# Diagnose
git worktree list
git fsck
git worktree prune

# Repair
git worktree repair
git worktree unlock path

# Force operations (use with caution)
git worktree remove --force path
git branch -D branch-name

---

Summary

Most git worktree issues fall into these categories:

1. Creation conflicts - Directory or branch conflicts
2. Permission issues - Filesystem restrictions
3. Corruption - Manual deletions or crashes
4. Cleanup problems - Uncommitted changes or locks

General troubleshooting approach:

1. Read error message carefully
2. Check git worktree list for current state
3. Use git worktree prune to clean orphans
4. Use --force flags only when necessary
5. Document unusual issues for team

Remember: Git worktrees are just checkouts in different directories. Most git commands work the same way - when in doubt, treat it like a normal git repository!