Git Worktree Management

A version control skill for using Git worktrees to work on multiple branches simultaneously without switching, enabling parallel development, hotfix workflows, and review-while-developing patterns.

When to Use

Choose Git Worktree Management when:

• Working on multiple branches simultaneously without stashing or switching
• Reviewing pull requests while continuing development on your current branch
• Applying hotfixes to production while a feature branch is in progress
• Running long test suites on one branch while developing on another

Consider alternatives when:

• Simple branch switching — use git switch or git checkout
• Cloning the repo separately — unnecessary when worktrees solve the same problem
• Temporary code exploration — use git stash for quick context switches

Quick Start

Copy
# Create a worktree for a feature branch
git worktree add ../my-project-feature feature-branch

# Create a new branch in a worktree
git worktree add -b hotfix/urgent ../my-project-hotfix main

# List all worktrees
git worktree list

# Remove a worktree when done
git worktree remove ../my-project-feature

Copy
#!/bin/bash
# Worktree management script

MAIN_REPO=$(git rev-parse --show-toplevel)
WORKTREE_DIR="${MAIN_REPO}/.worktrees"

create_worktree() {
    local branch=$1
    local name=${2:-$(echo "$branch" | tr '/' '-')}
    local path="${WORKTREE_DIR}/${name}"

    mkdir -p "$WORKTREE_DIR"

    if git show-ref --verify --quiet "refs/heads/${branch}"; then
        git worktree add "$path" "$branch"
    else
        git worktree add -b "$branch" "$path" HEAD
    fi

    echo "Worktree created at: $path"
    echo "cd $path"
}

list_worktrees() {
    echo "=== Active Worktrees ==="
    git worktree list --porcelain | while IFS= read -r line; do
        case "$line" in
            worktree*)
                path="${line#worktree }"
                echo -n "  Path: $path"
                ;;
            branch*)
                branch="${line#branch refs/heads/}"
                echo " | Branch: $branch"
                ;;
        esac
    done
}

cleanup_worktrees() {
    echo "Pruning stale worktrees..."
    git worktree prune
    echo "Remaining worktrees:"
    list_worktrees
}

case "${1}" in
    create) create_worktree "$2" "$3" ;;
    list)   list_worktrees ;;
    clean)  cleanup_worktrees ;;
    *)      echo "Usage: $0 {create|list|clean} [branch] [name]" ;;
esac

Core Concepts

Worktree vs Branch Switching

Aspect	git switch/checkout	git worktree
Working directory	Shared (one at a time)	Separate per branch
Uncommitted changes	Must stash or commit	Independent
File watchers	Restart needed	Always running
Build cache	Invalidated	Preserved per branch
Running processes	Must stop	Independent
Disk usage	Minimal	Extra per worktree

Workflow Patterns

Copy
# Pattern 1: Review PR while developing
# Main worktree: feature development
# Second worktree: PR review

git worktree add ../review-pr-123 pr-branch-123
cd ../review-pr-123
npm install  # Dependencies for this branch
npm test     # Run tests
# Review code, leave comments
cd ../main-project  # Back to feature work
git worktree remove ../review-pr-123

# Pattern 2: Hotfix while on feature branch
git worktree add -b hotfix/critical ../hotfix main
cd ../hotfix
# Apply fix, test, push
git push origin hotfix/critical
cd ../main-project
git worktree remove ../hotfix

# Pattern 3: Parallel testing
git worktree add ../test-env staging
cd ../test-env
npm run test:e2e  # Long-running tests
# Meanwhile, continue development in main worktree

Configuration

Option	Description	Default
worktree_directory	Base directory for worktrees	"../" or .worktrees/
auto_install_deps	Run npm install in new worktrees	false
prune_on_remove	Auto-prune stale references	true
shared_node_modules	Symlink node_modules between worktrees	false
lock_main_branch	Prevent force operations on main worktree	true
naming_convention	Worktree directory naming pattern	"{branch-name}"
max_worktrees	Maximum active worktrees	5
auto_cleanup	Remove worktrees for merged branches	false

Best Practices

1. Keep worktrees in a consistent location like a .worktrees/ directory at the same level as your main repo so they are easy to find and manage, rather than scattering them across the filesystem
2. Remove worktrees when done with git worktree remove to keep the list clean and prevent accumulation of stale directories that waste disk space
3. Use worktrees for long-running tasks like test suites, CI-like validation, or PR review sessions where you need to run the code while continuing development — do not create worktrees for quick one-minute checks
4. Share node_modules carefully by symlinking when dependencies are identical, but be aware that different branches may need different dependency versions; run npm install in each worktree to be safe
5. Run git worktree prune periodically to clean up references to worktrees whose directories were deleted manually without using git worktree remove

Common Issues

Worktree branch already checked out error: Git prevents checking out a branch that is already checked out in another worktree. If you need to work on the same branch, use the existing worktree. To force a different worktree on the same branch, remove the existing worktree first.

Node modules and build artifacts not shared: Each worktree is a separate working directory with its own node_modules and build output. This uses more disk space but prevents dependency conflicts. For large projects, consider using npm cache for faster installs or symbolic linking shared dependencies.

IDE not recognizing worktree as a git repository: Some IDEs do not detect the .git file (not directory) in worktrees that points to the main repository. Open the worktree directory directly as a project, and ensure your IDE supports worktrees (VS Code, JetBrains, and most modern IDEs handle this correctly).