Using Git Worktrees
Overview
Git worktrees create isolated workspaces that share the same repository, allowing you to work on multiple branches simultaneously without switching.
Core Principle: Systematic Directory Selection + Security Validation = Reliable Isolation.
Announce when starting: "I'm using the using-git-worktrees skill to set up an isolated workspace."
Directory Selection Process
Follow this priority order:
1. Check Existing Directories
bash
# Check in priority order
ls -d .worktrees 2>/dev/null # Preferred (hidden directory)
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 directly without asking.
3. Ask the User
If no existing directories and no preference in CLAUDE.md:
No worktree directory found. Where should I create the worktree?
1. .worktrees/ (project-local, hidden directory)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)
Which do you prefer?
Security Validation
Project-Local Directories (.worktrees or worktrees)
Must verify the directory is ignored before creating worktree:
bash
# Check if directory is ignored (follows 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 corresponding entry to .gitignore
- Commit the changes
- Proceed to create the worktree
Why this is critical: Prevent accidental commit of worktree content to the repository.
Global Directory (~/.config/superpowers/worktrees)
No .gitignore validation needed — 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 the corresponding setup commands:
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 Baseline Health
Run tests to ensure the worktree has a clean initial state:
bash
# Example - use project-specific commands
npm test
cargo test
pytest
go test ./...
If tests fail: Report the failure and ask whether to continue or troubleshoot.
If tests pass: Report readiness.
5. Report Location
Worktree ready: <full-path>
Tests passed (<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 |
| Baseline tests fail | Report failure + ask |
| No package.json/Cargo.toml | Skip dependency installation |
Common Mistakes
Skipping Ignore Validation
- Problem: Worktree content gets tracked, polluting git status
- Fix: Always use before creating project-local worktrees
Assuming Directory Location
- Problem: Causes inconsistency and violates project conventions
- Fix: Follow priority: Existing directories > CLAUDE.md > Ask
Continuing with Failed Tests
- Problem: Cannot distinguish new bugs from pre-existing issues
- Fix: Report failure and get explicit permission before continuing
Hardcoding Setup Commands
- Problem: Will fail on 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 passed]
Worktree ready: /Users/jesse/myproject/.worktrees/auth
Tests passed (47 tests, 0 failures)
Ready to implement auth feature
Red Lines
Never:
- Create a project-local worktree without verifying it's ignored
- Skip baseline test validation
- Continue with failed tests without asking
- Assume directory location when ambiguous
- Skip CLAUDE.md check
Always:
- Follow directory priority: Existing directories > CLAUDE.md > Ask
- Verify ignore status for project-local directories
- Auto-detect and run project setup
- Verify clean test baseline
Integration
Called by these skills:
- brainstorming (Phase 4) - Required when design is approved and implementation is needed
- subagent-driven-development - Required before executing any tasks
- executing-plans - Required before executing any tasks
- Any skill requiring an isolated workspace
Used with:
- finishing-a-development-branch - Required for cleanup after work is completed