Using Git Worktrees
Overview
Git worktrees establish independent workspaces that share the same repository, allowing you to work on multiple branches simultaneously without switching.
Core Principle: System directory selection + security verification = reliable isolation.
Declaration to start: "I'm using the using-git-worktrees skill to set up an isolated workspace."
Directory Selection Process
Please follow the following priority order:
1. Check Existing Directories
bash
# 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,
takes precedence.
2. Check CLAUDE.md
bash
grep -i "worktree.*director" CLAUDE.md 2>/dev/null
If preference is specified: Use it without asking.
3. Ask the User
If no directory exists and there's no preference in CLAUDE.md:
No worktree directory found. Where should I create worktrees?
1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)
Which would you prefer?
Security Verification
For project-local directories (.worktrees or worktrees)
Must verify the directory is ignored before creating the worktree:
bash
# Check if directory is ignored (respects local, global, and system gitignore)
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
If not ignored:
Follow Jesse's rule "Fix broken things immediately":
- Add the appropriate line to .gitignore
- Commit the changes
- Proceed to create the worktree
Why it matters: Prevent accidentally committing worktree content to the repository.
For global directories (~/.config/superpowers/worktrees)
No need for .gitignore verification - completely outside the project.
Creation Steps
1. Detect Project Name
bash
project=$(basename "$(git rev-parse --show-toplevel)")
2. Create Worktree
bash
# Determine full path
case $LOCATION in
.worktrees|worktrees)
path="$LOCATION/$BRANCH_NAME"
;;
~/.config/superpowers/worktrees/*)
path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
;;
esac
# Create worktree with new branch
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"
3. Run Project Setup
Automatically detect and run appropriate setup:
bash
# 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
4. Verify Clean Baseline
Run tests to ensure the worktree starts clean:
bash
# Examples - use project-appropriate command
npm test
cargo test
pytest
go test ./...
If tests fail: Report the failure and ask whether to continue or investigate.
If tests pass: Report readiness.
5. Announce Location
Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>
Quick Reference
| Scenario | Action |
|---|
| exists | Use it (verify ignored) |
| exists | Use it (verify ignored) |
| Both exist | Use |
| Neither exists | Check CLAUDE.md → Ask user |
| Directory not ignored | Add to .gitignore + commit |
| Tests fail during baseline | Report failure + ask |
| No package.json/Cargo.toml | Skip dependency installation |
Common Mistakes
Skipping Ignore Verification
- Problem: Worktree content is tracked, polluting git status
- Fix: Always use before creating project-local worktrees
Assuming Directory Location
- Problem: Causes inconsistencies, violates project conventions
- Fix: Follow priority: Existing > CLAUDE.md > Ask
Continuing with Failed Tests
- Problem: Cannot distinguish new errors from pre-existing issues
- Fix: Report failure, get explicit permission to continue
Hardcoding Setup Commands
- Problem: Breaks in projects using different tools
- Fix: Auto-detect from project files (package.json, etc.)
Example Workflow
You: I'm using the using-git-worktrees skill to set up an isolated workspace.
[Check .worktrees/ - exists]
[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
[Create worktree: git worktree add .worktrees/auth -b feature/auth]
[Run npm install]
[Run npm test - 47 passing]
Worktree ready at /Users/jesse/myproject/.worktrees/auth
Tests passing (47 tests, 0 failures)
Ready to implement auth feature
Red Flags
Never:
- Create a worktree without verifying it's ignored (project-local)
- Skip baseline test verification
- Continue with failed tests without asking
- Assume directory location when it's unclear
- Skip CLAUDE.md check
Always:
- Follow directory priority: Existing > CLAUDE.md > Ask
- Verify project-local directories are ignored
- Auto-detect and run project setup
- Verify clean test baseline
Integration
Callers:
- Brainstorm (Phase 4) - Required when design is approved and implementation follows
- Sub-agent Driven Development - Required before executing any tasks
- Execute Plan - Required before executing any tasks
- Any skill that requires independent workspaces
Pair With:
- Complete Development Branch - Required for cleanup after work is done