name: worktree
description: Manage git worktrees for parallel development. Use to work on multiple branches simultaneously without stashing or switching contexts.

Git Worktree Manager

Work on multiple branches simultaneously using git worktrees.

Prerequisites

# Git 2.5+ (worktrees built-in)
git --version

CLI Reference

List Worktrees

# List all worktrees
git worktree list

# Porcelain format (machine-readable)
git worktree list --porcelain

Create Worktree

# Create from existing branch
git worktree add ../feature-branch feature-branch

# Create new branch
git worktree add -b new-feature ../new-feature main

# Specific path
git worktree add /path/to/worktree branch-name

# Detached HEAD at commit
git worktree add --detach ../temp abc123

Remove Worktree

# Remove worktree
git worktree remove ../feature-branch

# Force remove (uncommitted changes)
git worktree remove --force ../feature-branch

# Prune stale worktrees
git worktree prune

Worktree Operations

# Move worktree
git worktree move ../old-path ../new-path

# Lock worktree (prevent pruning)
git worktree lock ../feature-branch
git worktree lock --reason "long-running task" ../feature-branch

# Unlock
git worktree unlock ../feature-branch

Workflow Patterns

Parallel Feature Development

# Main repo working on feature-a
cd ~/repos/myproject
git checkout feature-a

# Create worktree for feature-b
git worktree add ../myproject-feature-b feature-b

# Now you have two checkouts:
# ~/repos/myproject (feature-a)
# ~/repos/myproject-feature-b (feature-b)

Quick Bug Fix

# Currently working on feature
cd ~/repos/myproject

# Create worktree for hotfix
git worktree add ../myproject-hotfix -b hotfix/urgent main

# Fix bug in worktree
cd ../myproject-hotfix
# make changes
git commit -am "fix: urgent bug"
git push origin hotfix/urgent

# Create PR
gh pr create --base main --title "Hotfix: urgent bug"

# Clean up
cd ../myproject
git worktree remove ../myproject-hotfix

Review PR

# Create worktree for PR branch
git fetch origin pull/123/head:pr-123
git worktree add ../myproject-pr-123 pr-123

# Review and test
cd ../myproject-pr-123
npm install
npm test

# Clean up after review
cd ../myproject
git worktree remove ../myproject-pr-123
git branch -D pr-123

Long-Running Comparison

# Worktree for baseline
git worktree add ../myproject-baseline main

# Run tests on both
cd ~/repos/myproject
npm test > /tmp/feature-tests.log

cd ../myproject-baseline
npm test > /tmp/baseline-tests.log

diff /tmp/baseline-tests.log /tmp/feature-tests.log

Directory Structure

Recommended layout:

~/repos/
├── myproject/           # Main worktree (main branch)
├── myproject-feature-a/ # Feature worktree
├── myproject-feature-b/ # Another feature
└── myproject-hotfix/    # Hotfix worktree

Or nested:

~/repos/myproject/
├── main/      # Main worktree
├── features/
│   ├── auth/  # Feature worktree
│   └── ui/    # Feature worktree
└── hotfix/    # Hotfix worktree

Beads with Worktrees

When using beads (task tracker) with worktrees, disable the daemon:

# In shell config
export BEADS_NO_DAEMON=1

# Or per-command
bd --no-daemon ready
bd --no-daemon create "task"

Common Issues

Branch Already Checked Out

# Error: 'branch' is already checked out at '/path'
# Solution: Use different branch or remove other worktree
git worktree remove /path/to/other

Stale Worktree References

# Clean up deleted worktrees
git worktree prune

# Verbose output
git worktree prune --verbose

Shared Resources

Each worktree shares:
- .git directory (refs, objects)
- Remote configurations
- Hooks

Each worktree has separate:
- Working directory
- Index (staging area)
- HEAD

Scripts

Create Feature Worktree

#!/bin/bash
FEATURE=$1
BASE=${2:-main}

git worktree add -b feature/$FEATURE ../${PWD##*/}-$FEATURE $BASE
cd ../${PWD##*/}-$FEATURE
npm install
echo "Worktree created at $(pwd)"

Cleanup Old Worktrees

#!/bin/bash
# Remove worktrees for merged branches

for wt in $(git worktree list --porcelain | grep "^worktree" | cut -d' ' -f2); do
  branch=$(git -C "$wt" branch --show-current)
  if git branch --merged main | grep -q "$branch"; then
    echo "Removing merged worktree: $wt ($branch)"
    git worktree remove "$wt"
  fi
done
git worktree prune

Best Practices

1. Use descriptive paths - Include branch name in directory
2. Install dependencies - Run npm/yarn install in each worktree
3. Prune regularly - Clean up stale references
4. Don't nest worktrees - Keep them sibling directories
5. Lock long-running - Prevent accidental pruning
6. Separate IDE workspace - Each worktree gets own IDE window
7. Disable beads daemon - Prevent database conflicts