using-git-worktrees

Using Git Worktrees

Core Principle

Isolate feature work. Keep main clean.

Git worktrees let you work on multiple branches simultaneously in separate directories.

When to Use

• Starting a new feature
• Working on a bugfix while main development continues
• Need to context-switch without stashing
• Want clean separation between work streams

Setup Process

Step 1: Check for Existing Worktree Directory

# Check in priority order
ls -d .worktrees 2>/dev/null    # Preferred (hidden)
ls -d worktrees 2>/dev/null     # Alternative

If found: Use that directory. If both exist: .worktrees wins.

Step 2: Check CLAUDE.md for Preferences

grep -i "worktree.*director" CLAUDE.md 2>/dev/null

If preference specified: Use it without asking.

Step 3: If No Directory Exists

Ask the user:

No worktree directory found. Where should I create worktrees?
1. .worktrees/ (project-local, hidden)
2. worktrees/ (project-local, visible)
3. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Which would you prefer?

Step 4: Verify .gitignore

# Check if directory pattern in .gitignore
grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore

If not present, add it:

echo ".worktrees/" >> .gitignore
# or
echo "worktrees/" >> .gitignore

Creating a Worktree

Standard Creation

# Determine branch name from feature
BRANCH_NAME="feature/descriptive-name"

# Create worktree with new branch
git worktree add ".worktrees/$BRANCH_NAME" -b "$BRANCH_NAME"

# Navigate to worktree
cd ".worktrees/$BRANCH_NAME"

From Existing Branch

git worktree add ".worktrees/$BRANCH_NAME" "$BRANCH_NAME"

Post-Creation Setup

Install Dependencies

# Node.js
if [ -f package.json ]; then npm install; fi

# Rust
if [ -f Cargo.toml ]; then cargo build; fi

# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi

# Go
if [ -f go.mod ]; then go mod download; fi