git-worktrees

name	git-worktrees
description	Use when working on multiple features simultaneously. Creates isolated workspaces without branch switching, enabling parallel development.

Git Worktrees

Core Principle

Work on multiple features in parallel using git worktrees instead of constantly switching branches.

When to Use This Skill

• Working on multiple features simultaneously
• Need to quickly switch context without stashing
• Want to run tests on one branch while working on another
• Comparing implementations across branches
• Client requests urgent fix while working on feature

What Are Git Worktrees?

Git worktrees allow you to have multiple working directories for the same repository, each checked out to a different branch.

Traditional way:

git checkout feature-a
[work on feature-a]
git stash
git checkout feature-b
[work on feature-b]
git stash
git checkout feature-a
git stash pop

With worktrees:

# Both branches available simultaneously in different directories
cd ../project-feature-a    # Work on feature-a
cd ../project-feature-b    # Work on feature-b
cd ../project-hotfix        # Work on hotfix

Benefits

✅ No stashing: Changes stay in their worktree ✅ Parallel work: Different features in different terminals ✅ Independent testing: Test one branch while coding another ✅ Quick context switching: Just cd to different directory ✅ Clean state: Each worktree is independent

Git Worktree Basics

Creating a Worktree

# Basic syntax
git worktree add <path> <branch>

# Create worktree for existing branch
git worktree add ../project-feature-x feature/feature-x

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

# Create worktree from specific branch
git worktree add ../project-hotfix -b hotfix/security-patch main

Listing Worktrees

# List all worktrees
git worktree list

# Output example:
# /path/to/project        abc123 [main]
# /path/to/project-auth   def456 [feature/authentication]
# /path/to/project-api    ghi789 [feature/api-refactor]

Removing a Worktree

# After finishing work and merging the branch
git worktree remove ../project-feature-x

# Or if directory is already deleted
git worktree prune

Moving Between Worktrees

# Just use cd
cd ../project-auth        # Work on authentication
cd ../project-api         # Work on API
cd ../project             # Back to main worktree

Worktree Workflow Examples

Example 1: Parallel Feature Development

Scenario: Working on authentication (long-term) and need to add quick bug fix

# Setup main project
cd ~/projects/myapp
git checkout main

# Create worktree for authentication feature
git worktree add -b feature/authentication ../myapp-auth main

# Start working on authentication
cd ../myapp-auth
[make changes, run tests, commit]

# Client reports urgent bug while you're working
# No need to stash! Just create worktree for fix
cd ~/projects/myapp
git worktree add -b fix/urgent-bug ../myapp-bugfix main

# Fix the bug in separate worktree
cd ../myapp-bugfix
[fix bug, test, commit, push]

# Create PR for bug fix
gh pr create --title "fix: resolve urgent bug"

# Bug fix merged, clean up
git worktree remove ../myapp-bugfix

# Continue working on authentication without interruption
cd ../myapp-auth
[continue work...]

Example 2: Testing Across Branches

Scenario: Need to compare behavior between main and your feature branch

# Main worktree
cd ~/projects/myapp    # On main branch

# Feature worktree
git worktree add -b feature/new-api ../myapp-feature main
cd ../myapp-feature
[implement feature]

# Test your feature
./scripts/safe-test.sh npm test

# Compare with main branch behavior
cd ~/projects/myapp    # Main branch
./scripts/safe-test.sh npm test

# Run both simultaneously in different terminals
# Terminal 1: cd ~/projects/myapp && npm run dev
# Terminal 2: cd ../myapp-feature && npm run dev
# Compare on different ports

Example 3: Code Review Workflow

Scenario: Reviewing a PR while working on your own feature

# Your work in progress
cd ~/projects/myapp-my-feature
[your work...]

# Colleague asks for code review on their PR
cd ~/projects/myapp
git fetch origin
git worktree add ../myapp-review-pr123 pr-123

# Review the code
cd ../myapp-review-pr123
[review code, run tests, check functionality]

# Add review comments
gh pr review 123 --comment -b "LGTM! Tested locally, works great."

# Clean up review worktree
cd ~/projects/myapp
git worktree remove ../myapp-review-pr123

# Back to your work without any disruption
cd ../myapp-my-feature
[continue working...]

Worktree Organization Strategies

Strategy 1: Sibling Directories

~/projects/
├── myapp/              # Main worktree (main branch)
├── myapp-auth/         # feature/authentication
├── myapp-api/          # feature/api-refactor
└── myapp-bugfix/       # fix/login-error

Pros: Easy to see all worktrees, simple paths Cons: Clutters parent directory

Strategy 2: Subdirectory Organization

~/projects/myapp/
├── .git/               # Main repo
├── main/               # Main branch worktree
├── worktrees/
│   ├── auth/          # feature/authentication
│   ├── api/           # feature/api-refactor
│   └── bugfix/        # fix/login-error

Pros: Organized, all in one place Cons: Slightly longer paths

Strategy 3: Feature-Based Structure

~/projects/myapp/
├── .git/
├── production/         # main branch
├── staging/            # staging branch
├── features/
│   ├── authentication/
│   ├── api-refactor/
│   └── user-profile/
└── fixes/
    ├── login-error/
    └── memory-leak/

Pros: Very organized, clear purpose Cons: More complex setup

Worktree Best Practices

DO:

✅ Name worktree directories clearly (match branch name) ✅ Remove worktrees after branch is merged ✅ Run git worktree prune periodically ✅ Use worktrees for truly parallel work ✅ Keep worktrees in predictable locations

DON'T:

❌ Create too many worktrees (keep it manageable) ❌ Leave stale worktrees around after branches merged ❌ Use worktrees for trivial branch switches ❌ Forget which worktree you're in (use git prompt)

Worktree Cleanup

Removing Merged Worktrees

# After feature is merged, remove worktree
git worktree remove ../myapp-feature

# Delete the merged branch
git branch -d feature/feature-name

# Prune any stale worktree references
git worktree prune

Finding Stale Worktrees

# List all worktrees
git worktree list

# Check which branches are merged
git branch --merged

# Remove worktrees for merged branches
for worktree in $(git worktree list --porcelain | grep worktree | cut -d' ' -f2); do
    cd $worktree
    branch=$(git branch --show-current)
    if git branch --merged main | grep -q "$branch"; then
        echo "Removing merged worktree: $worktree"
        git worktree remove $worktree
    fi
done

Integration with Skills

Use with:

• dispatching-parallel-agents - Run multiple agents in different worktrees
• git-workflow - Standard git practices apply in each worktree
• executing-plans - Execute different plans in parallel
• code-review - Review PRs in separate worktrees

Workflow:

1. Create worktree for feature: git worktree add
2. Work on feature: Use brainstorming, writing-plans, executing-plans
3. Test in worktree: Use database-backup for each worktree
4. Review in main worktree: Compare implementations
5. Merge and cleanup: Remove worktree

Common Issues and Solutions

Issue 1: Worktree Creation Fails

Error: fatal: 'path' already exists

Solution:

# Remove the directory first
rm -rf ../myapp-feature
git worktree add ../myapp-feature feature/feature-name

# Or use a different path
git worktree add ../myapp-feature-v2 feature/feature-name

Issue 2: Branch Checked Out in Another Worktree

Error: fatal: 'branch' is already checked out at 'path'

Solution:

# A branch can only be checked out in one worktree at a time
# Either:
# 1. Remove the existing worktree
git worktree remove path/to/existing/worktree

# 2. Or create with different branch name
git worktree add -b feature/feature-name-v2 ../myapp-feature feature/feature-name

Issue 3: Forgot Which Worktree You're In

Solution:

# Show current worktree path
pwd

# Show current branch
git branch --show-current

# Add to shell prompt (add to .bashrc or .zshrc)
parse_git_branch() {
    git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/(\1)/'
}
PS1="\w \$(parse_git_branch) $ "

Issue 4: Stale Worktree References

Error: Worktree listed but directory doesn't exist

Solution:

# Prune stale references
git worktree prune -v

# Force remove if needed
git worktree remove --force path/to/worktree

Advanced Worktree Usage

Worktrees for CI/CD Testing

# Create worktree for CI testing
git worktree add ../myapp-ci-test feature/feature-name

# Run CI tests in isolation
cd ../myapp-ci-test
./scripts/safe-test.sh npm run ci-test

# Clean up
cd -
git worktree remove ../myapp-ci-test

Worktrees for Deployment Branches

# Keep production and staging as worktrees
git worktree add ../myapp-production production
git worktree add ../myapp-staging staging

# Deploy from dedicated worktrees
cd ../myapp-production
git pull origin production
[run deployment script]

cd ../myapp-staging
git pull origin staging
[run staging deployment]

Worktree Checklist

Before creating worktree:

• Do I really need parallel work? (worktrees add complexity)
• Have I chosen a clear, descriptive path?
• Is the base branch correct?

While working in worktree:

• Am I aware which worktree I'm in?
• Have I committed changes regularly?
• Am I using proper git workflow in this worktree?

After finishing work:

• Has the branch been merged?
• Have I removed the worktree?
• Have I deleted the merged branch?
• Have I run git worktree prune?

Authority

This skill is based on:

• Git worktrees feature (since Git 2.5)
• Professional development: Parallel work is common
• Efficiency: Context switching is expensive
• Best practices from the Superpowers framework

Social Proof: Many professional developers use worktrees for parallel feature development.

Your Commitment

Before using worktrees:

• I understand worktrees allow parallel work
• I will keep worktrees organized
• I will clean up merged worktrees
• I will not overuse worktrees (only when needed)

---

Bottom Line: Worktrees enable true parallel development. Use them when you need to work on multiple features simultaneously without constant branch switching. Clean up when done.