nhouseholder/using-git-worktrees

Using Git Worktrees

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.

Directory Selection (Priority Order)

1. Check Existing Directories

ls -d .worktrees 2>/dev/null     # Preferred (hidden)
ls -d worktrees 2>/dev/null      # Alternative

If both exist, .worktrees wins.

2. Check CLAUDE.md

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)

Safety Verification

Project-Local Directories

MUST verify directory is ignored before creating worktree:

git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

If NOT ignored: Add to .gitignore, commit, then proceed.

Global Directory (~/.config/superpowers/worktrees)

No .gitignore verification needed — outside project entirely.

Creation Steps

1. Detect Project Name

project=$(basename "$(git rev-parse --show-toplevel)")

2. Create Worktree

# Project-local
git worktree add ".worktrees/$BRANCH_NAME" -b "$BRANCH_NAME"

# Global
git worktree add "$HOME/.config/superpowers/worktrees/$project/$BRANCH_NAME" -b "$BRANCH_NAME"

3. Run Project Setup

Auto-detect and run:

[ -f package.json ] && npm install
[ -f Cargo.toml ] && cargo build
[ -f requirements.txt ] && pip install -r requirements.txt
[ -f pyproject.toml ] && poetry install
[ -f go.mod ] && go mod download

4. Verify Clean Baseline

Run project-appropriate tests. If tests fail, report failures and ask whether to proceed.

5. Report

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

| Mistake | Fix | |---------|-----| | Skipping ignore verification | Always git check-ignore before creating project-local worktree | | Assuming directory location | Follow priority: existing > CLAUDE.md > ask | | Proceeding with failing tests | Report failures, get explicit permission | | Hardcoding setup commands | Auto-detect from project files |