liauw-media/git-worktrees

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.