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

Run Initial Tests

# Run test suite
npm test  # or appropriate command

# Report status

If tests fail: Report failures, ask whether to proceed or investigate. If tests pass: Report ready.

Worktree Management

List Worktrees

git worktree list

Remove Worktree

# After merging feature branch
git worktree remove ".worktrees/feature/branch-name"

# Force remove (if needed)
git worktree remove --force ".worktrees/feature/branch-name"

Prune Stale Worktrees

git worktree prune

Best Practices

Naming Convention

• feature/descriptive-name for features
• bugfix/issue-number-description for bugs
• hotfix/critical-issue for urgent fixes

Keep Worktrees Focused

• One feature per worktree
• Merge and remove when done
• Don't let worktrees accumulate

Sync Regularly

# In worktree, get latest from main
git fetch origin
git rebase origin/main

Completion Checklist

When feature is complete:

1. All tests pass
2. Code reviewed
3. Merged to main
4. Worktree removed
5. Branch deleted (if desired)

# Full cleanup
git checkout main
git pull
git worktree remove ".worktrees/feature/name"
git branch -d feature/name

Announcement Template

At start of worktree creation:

"I'm using the using-git-worktrees skill to set up an isolated workspace for [feature name]."

On completion:

"Worktree ready at [full-path]
Tests passing ([N] tests, 0 failures)
Ready to implement [feature-name]"

Converted and distributed by TomeVault — claim your Tome and manage your conversions.