using-git-worktrees

# Using Git Worktrees ## 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 Process Follow this 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, `.worktrees` wins. ### 2. Check CLAUDE.md ```bash grep -i "worktree.*director" CLAUDE.md 2>/dev/null ``` **If preference specified:** Use it without asking. ### 3. Ask User If no directory exists and no CLAUDE.md preference: ``` 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? ``` ## Safety Verification ### For Project-Local Directories (.worktrees or worktrees) **MUST verify directory is ignored before creating 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:** Per Jesse's rule "Fix broken things immediately": 1. Add appropriate line to .gitignore 2. Commit the change 3. Proceed with worktree creation **Why critical:** Prevents accidentally committing worktree contents to repository. ### For Global Directory (~/.config/superpowers/worktrees) No .gitignore verification needed - outside project entirely. ## 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 Auto-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 worktree starts clean: ```bash # Examples - use project-appropriate command npm test cargo test pytest go test ./... ``` **If tests fail:** Report failures, ask whether to proceed or investigate. **If tests pass:** Report ready. ### 5. Report Location ``` Worktree ready at <full-path> Tests passing (<N> tests, 0 failures) Ready to implement <feature-name> ``` ## Quick Reference | Situation | Action | |-----------|--------| | `.worktrees/` exists | Use it (verify ignored) | | `worktrees/` exists | Use it (verify ignored) | | Both exist | Use `.worktrees/` | | Neither exists | Check CLAUDE.md → Ask user | | Directory not ignored | Add to .gitignore + commit | | Tests fail during baseline | Report failures + ask | | No package.json/Cargo.toml | Skip dependency install | ## Common Mistakes ### Skipping ignore verification - **Problem:** Worktree contents get tracked, pollute git status - **Fix:** Always use `git check-ignore` before creating project-local worktree ### Assuming directory location - **Problem:** Creates inconsistency, violates project conventions - **Fix:** Follow priority: existing > CLAUDE.md > ask ### Proceeding with failing tests - **Problem:** Can't distinguish new bugs from pre-existing issues - **Fix:** Report failures, get explicit permission to proceed ### Hardcoding setup commands - **Problem:** Breaks 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 passing] Worktree ready at /Users/jesse/myproject/.worktrees/auth Tests passing (47 tests, 0 failures) Ready to implement auth feature ``` ## Red Flags **Never:** - Create worktree without verifying it's ignored (project-local) - Skip baseline test verification - Proceed with failing tests without asking - Assume directory location when ambiguous - Skip CLAUDE.md check **Always:** - Follow directory priority: existing > CLAUDE.md > ask - Verify directory is ignored for project-local - Auto-detect and run project setup - Verify clean test baseline ## Integration **Called by:** - **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows - **subagent-driven-development** - REQUIRED before executing any tasks - **executing-plans** - REQUIRED before executing any tasks - Any skill needing isolated workspace **Pairs with:** - **finishing-a-development-branch** - REQUIRED for cleanup after work complete