Using Git Worktrees

1---2name: using-git-worktrees3description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification4---5 6# Using Git Worktrees7 8## Overview9 10Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.11 12**Core principle:** Systematic directory selection + safety verification = reliable isolation.13 14**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."15 16## Directory Selection Process17 18Follow this priority order:19 20### 1. Check Existing Directories21 22```bash23# Check in priority order24ls -d .worktrees 2>/dev/null     # Preferred (hidden)25ls -d worktrees 2>/dev/null      # Alternative26```27 28**If found:** Use that directory. If both exist, `.worktrees` wins.29 30### 2. Check CLAUDE.md31 32```bash33grep -i "worktree.*director" CLAUDE.md 2>/dev/null34```35 36**If preference specified:** Use it without asking.37 38### 3. Ask User39 40If no directory exists and no CLAUDE.md preference:41 42```43No worktree directory found. Where should I create worktrees?44 451. .worktrees/ (project-local, hidden)462. ~/.config/superpowers/worktrees/<project-name>/ (global location)47 48Which would you prefer?49```50 51## Safety Verification52 53### For Project-Local Directories (.worktrees or worktrees)54 55**MUST verify directory is ignored before creating worktree:**56 57```bash58# Check if directory is ignored (respects local, global, and system gitignore)59git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null60```61 62**If NOT ignored:**63 64Per Jesse's rule "Fix broken things immediately":651. Add appropriate line to .gitignore662. Commit the change673. Proceed with worktree creation68 69**Why critical:** Prevents accidentally committing worktree contents to repository.70 71### For Global Directory (~/.config/superpowers/worktrees)72 73No .gitignore verification needed - outside project entirely.74 75## Creation Steps76 77### 1. Detect Project Name78 79```bash80project=$(basename "$(git rev-parse --show-toplevel)")81```82 83### 2. Create Worktree84 85```bash86# Determine full path87case $LOCATION in88  .worktrees|worktrees)89    path="$LOCATION/$BRANCH_NAME"90    ;;91  ~/.config/superpowers/worktrees/*)92    path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"93    ;;94esac95 96# Create worktree with new branch97git worktree add "$path" -b "$BRANCH_NAME"98cd "$path"99```100 101### 3. Run Project Setup102 103Auto-detect and run appropriate setup:104 105```bash106# Node.js107if [ -f package.json ]; then npm install; fi108 109# Rust110if [ -f Cargo.toml ]; then cargo build; fi111 112# Python113if [ -f requirements.txt ]; then pip install -r requirements.txt; fi114if [ -f pyproject.toml ]; then poetry install; fi115 116# Go117if [ -f go.mod ]; then go mod download; fi118```119 120### 4. Verify Clean Baseline121 122Run tests to ensure worktree starts clean:123 124```bash125# Examples - use project-appropriate command126npm test127cargo test128pytest129go test ./...130```131 132**If tests fail:** Report failures, ask whether to proceed or investigate.133 134**If tests pass:** Report ready.135 136### 5. Report Location137 138```139Worktree ready at <full-path>140Tests passing (<N> tests, 0 failures)141Ready to implement <feature-name>142```143 144## Quick Reference145 146| Situation | Action |147|-----------|--------|148| `.worktrees/` exists | Use it (verify ignored) |149| `worktrees/` exists | Use it (verify ignored) |150| Both exist | Use `.worktrees/` |151| Neither exists | Check CLAUDE.md → Ask user |152| Directory not ignored | Add to .gitignore + commit |153| Tests fail during baseline | Report failures + ask |154| No package.json/Cargo.toml | Skip dependency install |155 156## Common Mistakes157 158### Skipping ignore verification159 160- **Problem:** Worktree contents get tracked, pollute git status161- **Fix:** Always use `git check-ignore` before creating project-local worktree162 163### Assuming directory location164 165- **Problem:** Creates inconsistency, violates project conventions166- **Fix:** Follow priority: existing > CLAUDE.md > ask167 168### Proceeding with failing tests169 170- **Problem:** Can't distinguish new bugs from pre-existing issues171- **Fix:** Report failures, get explicit permission to proceed172 173### Hardcoding setup commands174 175- **Problem:** Breaks on projects using different tools176- **Fix:** Auto-detect from project files (package.json, etc.)177 178## Example Workflow179 180```181You: I'm using the using-git-worktrees skill to set up an isolated workspace.182 183[Check .worktrees/ - exists]184[Verify ignored - git check-ignore confirms .worktrees/ is ignored]185[Create worktree: git worktree add .worktrees/auth -b feature/auth]186[Run npm install]187[Run npm test - 47 passing]188 189Worktree ready at /Users/jesse/myproject/.worktrees/auth190Tests passing (47 tests, 0 failures)191Ready to implement auth feature192```193 194## Red Flags195 196**Never:**197- Create worktree without verifying it's ignored (project-local)198- Skip baseline test verification199- Proceed with failing tests without asking200- Assume directory location when ambiguous201- Skip CLAUDE.md check202 203**Always:**204- Follow directory priority: existing > CLAUDE.md > ask205- Verify directory is ignored for project-local206- Auto-detect and run project setup207- Verify clean test baseline208 209## Integration210 211**Called by:**212- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows213- **subagent-driven-development** - REQUIRED before executing any tasks214- **executing-plans** - REQUIRED before executing any tasks215- Any skill needing isolated workspace216 217**Pairs with:**218- **finishing-a-development-branch** - REQUIRED for cleanup after work complete