Using Git Worktrees

1---
2name: using-git-worktrees
3description: 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 verification
4---
5 
6# Using Git Worktrees
7 
8## Overview
9 
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 Process
17 
18Follow this priority order:
19 
20### 1. Check Existing Directories
21 
22```bash
23# Check in priority order
24ls -d .worktrees 2>/dev/null     # Preferred (hidden)
25ls -d worktrees 2>/dev/null      # Alternative
26```
27 
28**If found:** Use that directory. If both exist, `.worktrees` wins.
29 
30### 2. Check CLAUDE.md
31 
32```bash
33grep -i "worktree.*director" CLAUDE.md 2>/dev/null
34```
35 
36**If preference specified:** Use it without asking.
37 
38### 3. Ask User
39 
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 Verification
52 
53### For Project-Local Directories (.worktrees or worktrees)
54 
55**MUST verify directory is ignored before creating worktree:**
56 
57```bash
58# 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/null
60```
61 
62**If NOT ignored:**
63 
64Per Jesse's rule "Fix broken things immediately":
651. Add appropriate line to .gitignore
662. Commit the change
673. Proceed with worktree creation
68 
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 Steps
76 
77### 1. Detect Project Name
78 
79```bash
80project=$(basename "$(git rev-parse --show-toplevel)")
81```
82 
83### 2. Create Worktree
84 
85```bash
86# Determine full path
87case $LOCATION in
88  .worktrees|worktrees)
89    path="$LOCATION/$BRANCH_NAME"
90    ;;
91  ~/.config/superpowers/worktrees/*)
92    path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
93    ;;
94esac
95 
96# Create worktree with new branch
97git worktree add "$path" -b "$BRANCH_NAME"
98cd "$path"
99```
100 
101### 3. Run Project Setup
102 
103Auto-detect and run appropriate setup:
104 
105```bash
106# Node.js
107if [ -f package.json ]; then npm install; fi
108 
109# Rust
110if [ -f Cargo.toml ]; then cargo build; fi
111 
112# Python
113if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
114if [ -f pyproject.toml ]; then poetry install; fi
115 
116# Go
117if [ -f go.mod ]; then go mod download; fi
118```
119 
120### 4. Verify Clean Baseline
121 
122Run tests to ensure worktree starts clean:
123 
124```bash
125# Examples - use project-appropriate command
126npm test
127cargo test
128pytest
129go 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 Location
137 
138```
139Worktree ready at <full-path>
140Tests passing (<N> tests, 0 failures)
141Ready to implement <feature-name>
142```
143 
144## Quick Reference
145 
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 Mistakes
157 
158### Skipping ignore verification
159 
160- **Problem:** Worktree contents get tracked, pollute git status
161- **Fix:** Always use `git check-ignore` before creating project-local worktree
162 
163### Assuming directory location
164 
165- **Problem:** Creates inconsistency, violates project conventions
166- **Fix:** Follow priority: existing > CLAUDE.md > ask
167 
168### Proceeding with failing tests
169 
170- **Problem:** Can't distinguish new bugs from pre-existing issues
171- **Fix:** Report failures, get explicit permission to proceed
172 
173### Hardcoding setup commands
174 
175- **Problem:** Breaks on projects using different tools
176- **Fix:** Auto-detect from project files (package.json, etc.)
177 
178## Example Workflow
179 
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/auth
190Tests passing (47 tests, 0 failures)
191Ready to implement auth feature
192```
193 
194## Red Flags
195 
196**Never:**
197- Create worktree without verifying it's ignored (project-local)
198- Skip baseline test verification
199- Proceed with failing tests without asking
200- Assume directory location when ambiguous
201- Skip CLAUDE.md check
202 
203**Always:**
204- Follow directory priority: existing > CLAUDE.md > ask
205- Verify directory is ignored for project-local
206- Auto-detect and run project setup
207- Verify clean test baseline
208 
209## Integration
210 
211**Called by:**
212- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
213- Any skill needing isolated workspace
214 
215**Pairs with:**
216- **finishing-a-development-branch** - REQUIRED for cleanup after work complete
217- **executing-plans** or **subagent-driven-development** - Work happens in this worktree
218