using-git-worktrees

Using Git Worktrees

Source: obra/superpowers (MIT)

Overview

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.

Core principle: Systematic directory selection + safety verification = reliable isolation.

Announce at start: "I'm using the using-git-worktrees skill to set up an isolated workspace."

Directory Selection

Follow this priority order:

1. Check existing: .worktrees/ or worktrees/ (prefer .worktrees)
2. Check project config: Look for worktree directory preference in CLAUDE.md, AGENTS.md, or similar
3. Ask user if no directory exists and no preference found

Safety Verification (Project-Local)

MUST verify directory is ignored before creating worktree:

git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

If NOT ignored: Add to .gitignore, commit, then proceed. Prevents accidentally committing worktree contents.

Creation Steps

1. Create Worktree

# Determine path (e.g., .worktrees/<branch-name>)
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

2. Run Project Setup

Auto-detect and run appropriate setup:

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

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

# Rust, Go, etc.

3. Verify Clean Baseline

Run tests to ensure worktree starts clean:

npm test / pytest / cargo test / go test ./...

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

If tests pass: Report ready.

4. Report Location

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

Red Flags

Never:

• Create worktree without verifying it's ignored (project-local)
• Skip baseline test verification
• Proceed with failing tests without asking

Always:

• Verify directory is ignored for project-local
• Auto-detect and run project setup
• Verify clean test baseline

Integration

Pairs with: finishing-a-development-branch — cleanup worktree after work complete.