Git Worktree Errors

Overview

Forge uses git worktrees to isolate task execution. Each task runs in its own worktree, preventing conflicts and allowing parallel development. However, this can occasionally cause issues.

Common Worktree Errors

Worktree Creation Failed

Problem: fatal: could not create worktree Causes & Solutions:

Not a Git Repository

# Verify you're in a git repo
git status

# If not, initialize
git init

# Add remote if needed
git remote add origin https://github.com/owner/repo.git

# Make initial commit
git add .
git commit -m "Initial commit"

Dirty Working Directory

# Stash uncommitted changes
git stash

# Or commit them
git add .
git commit -m "WIP: save changes"

# Try task again

Disk Space Issue

# Check available space
df -h

# Clean up old worktrees
rm -rf .forge/worktrees/*

# Or via Forge UI
# Settings → Cleanup → Remove Old Worktrees

Permission Error

# Check permissions on .forge directory
ls -la .forge

# Fix permissions
chmod -R 755 .forge/worktrees

# Ensure you own the directory
sudo chown -R $USER .forge

Worktree Already Exists

Problem: fatal: worktree already exists Solution:

# List existing worktrees
git worktree list

# Remove stale worktree
git worktree remove .forge/worktrees/task-123-attempt-1

# Or force remove if it's corrupted
git worktree remove --force .forge/worktrees/task-123-attempt-1

# Prune worktree references
git worktree prune

# Try creating task again

Cannot Remove Worktree

Problem: fatal: worktree contains modified or untracked files Solution:

# Navigate to worktree
cd .forge/worktrees/task-123-attempt-1

# See what's modified
git status

# Option 1: Stash changes
git stash

# Option 2: Discard changes
git reset --hard HEAD
git clean -fd

# Option 3: Force remove (loses changes)
cd ../..
git worktree remove --force .forge/worktrees/task-123-attempt-1

Orphaned Worktrees

Problem: Worktree directories exist but git doesn’t know about them Symptoms:

.forge/worktrees/ has directories
git worktree list doesn’t show them
Disk space consumed

Solution:

# List git's known worktrees
git worktree list

# List filesystem worktrees
ls -la .forge/worktrees/

# Clean up orphans manually
rm -rf .forge/worktrees/task-*

# Prune git worktree references
git worktree prune

# Or use Forge's cleanup
# Settings → Cleanup → Remove Orphaned Worktrees

Automatic Cleanup:

// Enable in .forge/config.json
{
  "worktrees": {
    "cleanup_on_exit": true,
    "auto_delete_merged": true
  }
}

Branch Issues

Branch Already Exists

Problem: fatal: a branch named 'forge/task-123' already exists Solution:

# Delete the old branch
git branch -D forge/task-123

# Or delete from both local and remote
git branch -D forge/task-123
git push origin --delete forge/task-123

# Retry task creation

Detached HEAD State

Problem: Worktree is in detached HEAD state Solution:

# Navigate to worktree
cd .forge/worktrees/task-123-attempt-1

# Check current state
git status

# Create and checkout branch
git checkout -b forge/task-123

# Or checkout existing branch
git checkout main
git checkout -b forge/task-123

Cannot Switch Branches

Problem: error: you need to resolve your current index first Solution:

cd .forge/worktrees/task-123-attempt-1

# Reset index
git reset

# Or discard all changes
git reset --hard HEAD

# Clean untracked files
git clean -fd

Merge Conflicts

Conflicts After Task Completion

Problem: Merge conflicts when merging worktree back to main Solution:

Identify Conflicts

cd .forge/worktrees/task-123-attempt-1

# Check for conflicts
git status

# View conflicted files
git diff --name-only --diff-filter=U

Resolve Conflicts

# Open conflicted files in editor
# Look for conflict markers:
# <<<<<<< HEAD
# =======
# >>>>>>> branch

# Edit files to resolve
vim conflicted-file.ts

# Or use merge tool
git mergetool

Mark as Resolved

# Add resolved files
git add conflicted-file.ts

# Complete merge
git commit

Merge to Main

# Return to main repo
cd ../../..

# Merge the worktree branch
git merge forge/task-123

# Or via Forge UI
# Review → Approve → Merge

Preventing Merge Conflicts

Best Practices:

Keep main branch updated:
```
git checkout main
git pull origin main
```

Rebase before merging:

cd .forge/worktrees/task-123-attempt-1
git fetch origin
git rebase origin/main

Use small, focused tasks:
- Smaller changes = fewer conflicts
- Complete tasks quickly
Coordinate with team:
- Avoid working on same files simultaneously
- Use task dependencies in Forge

Performance Issues

Too Many Worktrees

Problem: Hundreds of worktrees consuming disk space Solution:

# Check worktree count
ls .forge/worktrees/ | wc -l

# List worktrees with sizes
du -sh .forge/worktrees/*

# Clean up completed tasks
# Via Forge UI: Settings → Cleanup

# Or manually remove old worktrees
find .forge/worktrees -type d -mtime +7 -exec rm -rf {} +

# Prune git references
git worktree prune

Configure Auto-cleanup:

{
  "worktrees": {
    "auto_delete_merged": true,
    "cleanup_on_exit": true,
    "max_concurrent": 5
  }
}

Slow Worktree Creation

Problem: Creating worktrees takes very long Causes & Solutions:

Large Repository

# Check repo size
du -sh .git

# Use shallow clone for worktrees
git config worktree.guessRemote true

# Clean up old refs
git gc --aggressive --prune=now

Many Submodules

# Skip submodule initialization in worktrees
git config worktree.submodules false

# Or update submodules only when needed

Disk I/O Bottleneck

# Move worktrees to faster disk
{
  "worktrees": {
    "base_path": "/mnt/fast-ssd/forge-worktrees"
  }
}

Debug Mode

Enable worktree debugging to diagnose issues:

# Disable automatic cleanup
export DISABLE_WORKTREE_ORPHAN_CLEANUP=1

# Enable detailed logging
export RUST_LOG=debug

# Run Forge
automagik-forge

# Check logs for worktree operations
# Look for "worktree" in output

Manual Worktree Management

If Forge’s automatic worktree management fails, use git directly:

Create Worktree Manually

# Create worktree for task
git worktree add .forge/worktrees/task-123-attempt-1 -b forge/task-123

# Do work in worktree
cd .forge/worktrees/task-123-attempt-1
# ... make changes ...

# Commit
git add .
git commit -m "Implement feature"

# Return to main repo
cd ../../..

# Merge
git merge forge/task-123

# Remove worktree
git worktree remove .forge/worktrees/task-123-attempt-1

List All Worktrees

# Show all worktrees
git worktree list

# Example output:
# /path/to/repo        a1b2c3d [main]
# /path/to/repo/.forge/worktrees/task-1  d4e5f6g [forge/task-1]
# /path/to/repo/.forge/worktrees/task-2  h7i8j9k [forge/task-2]

Remove All Worktrees

# Get list of worktree paths
git worktree list --porcelain | grep worktree | cut -d' ' -f2

# Remove each worktree
git worktree list --porcelain | grep worktree | cut -d' ' -f2 | while read dir; do
  [[ "$dir" != *"/.forge/worktrees/"* ]] || git worktree remove "$dir"
done

# Prune references
git worktree prune

Recovery Procedures

Corrupted Worktree

Problem: Worktree is corrupted and won’t work Solution:

# Force remove corrupted worktree
git worktree remove --force .forge/worktrees/task-123-attempt-1

# Delete directory if still exists
rm -rf .forge/worktrees/task-123-attempt-1

# Delete branch
git branch -D forge/task-123

# Prune references
git worktree prune

# Recreate task in Forge UI

Complete Reset

Problem: Worktree system completely broken Solution:

# BACKUP FIRST
cp -r .forge .forge-backup

# Remove all worktrees
rm -rf .forge/worktrees/*

# Prune all worktree references
git worktree prune

# Delete all forge branches
git branch | grep 'forge/' | xargs git branch -D

# Reset Forge database
rm .forge/db.sqlite

# Restart Forge
automagik-forge

Next Steps

Common Issues

General troubleshooting guide

API Errors

API connection problems

Git Worktree Docs

Learn how git worktrees work in Forge

Discord Support

Get help from the community

Getting Started

Learn

Configuration

Reference

Troubleshooting

Overview

Common Worktree Errors

Worktree Creation Failed

Worktree Already Exists

Cannot Remove Worktree

Orphaned Worktrees

Branch Issues

Branch Already Exists

Detached HEAD State

Cannot Switch Branches

Merge Conflicts

Conflicts After Task Completion

Preventing Merge Conflicts

Performance Issues

Too Many Worktrees

Slow Worktree Creation

Debug Mode

Manual Worktree Management

Create Worktree Manually

List All Worktrees

Remove All Worktrees

Recovery Procedures

Corrupted Worktree

Complete Reset

Next Steps

Common Issues

API Errors

Git Worktree Docs

Discord Support

Getting Started

Learn

Configuration

Reference

Troubleshooting

Documentation Index

​Overview

​Common Worktree Errors

​Worktree Creation Failed

​Worktree Already Exists

​Cannot Remove Worktree

​Orphaned Worktrees

​Branch Issues

​Branch Already Exists

​Detached HEAD State

​Cannot Switch Branches

​Merge Conflicts

​Conflicts After Task Completion

​Preventing Merge Conflicts

​Performance Issues

​Too Many Worktrees

​Slow Worktree Creation

​Debug Mode

​Manual Worktree Management

​Create Worktree Manually

​List All Worktrees

​Remove All Worktrees

​Recovery Procedures

​Corrupted Worktree

​Complete Reset

​Next Steps

Common Issues

API Errors

Git Worktree Docs

Discord Support

Overview

Common Worktree Errors

Worktree Creation Failed

Worktree Already Exists

Cannot Remove Worktree

Orphaned Worktrees

Branch Issues

Branch Already Exists

Detached HEAD State

Cannot Switch Branches

Merge Conflicts

Conflicts After Task Completion

Preventing Merge Conflicts

Performance Issues

Too Many Worktrees

Slow Worktree Creation

Debug Mode

Manual Worktree Management

Create Worktree Manually

List All Worktrees

Remove All Worktrees

Recovery Procedures

Corrupted Worktree

Complete Reset

Next Steps