vt-c-using-git-worktrees¶

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

Plugin: vt-base
Category: Tooling
Command: /vt-c-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."

Worktree Roles¶

Before creating a new worktree, know what the existing ones are for. V025 uses three worktree roles, each defined by the branch it holds:

Role	Branch	Purpose
Main-Holder	`main`	The worktree that currently holds `main` — often none; `main` is usually checked out nowhere and gets a holder only transiently, at merge time.
Active-Workspace	long-lived `chore/` / `docs/`	The repo-root checkout where tooling commands run and commit between merges to `main`; renamed in place when its name drifts.
Feature	`feature/spec-NNN-*`	One per active spec, under `.worktrees/feature/`; created from `main`, merged back after `/vt-d-complete`.

Full roles, standard procedures (merge into main, sync after main-merge, rename), anti-pattern error signatures, and the spec-numbering-across-branches procedure: docs/solutions/patterns/v025-multi-worktree-workflow.md.

Directory Selection Process¶

Follow this priority order:

1. Check Existing Directories¶

# 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¶

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 .gitignore before creating worktree:

# Check if directory pattern in .gitignore
grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore

If NOT in .gitignore:

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¶

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

2. Create Worktree¶

# 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"

Next Steps — Open Your Worktree¶

After creating a worktree, always display:

## Next Steps — Open your worktree

**Option A: VS Code** (opens new window with worktree as root)
code <absolute-worktree-path>

**Option B: Terminal + Claude CLI** (start Claude directly in worktree)
cd <absolute-worktree-path> && claude

Use the absolute worktree path. Quote paths that contain spaces.

Heads-up: gitignored files (.env*.local etc.) are NOT copied by git worktree add. If your dev-server needs them, see Common Mistakes below.

3. Run Project Setup¶

Auto-detect and run appropriate setup:

# 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:

# 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>

Native `--worktree` Flag (Preferred for Claude Code)¶

Claude Code v2.1.50+ supports a native --worktree flag that automates worktree creation:

claude --worktree feature/auth          # Named worktree + session
claude --worktree feature/auth --dir    # Navigate directly into worktree
claude -w                                # Auto-named worktree

Advantages over manual git worktree add: - Creates worktree + branch + session in one command - Stores under .claude/worktrees/ (Claude's convention) - Automatic session resume when reusing the same name - Ctrl+W to view all active sessions across worktrees

When to use native flag vs manual setup: - Use --worktree for Claude Code sessions (simpler, integrated) - Use manual git worktree add when you need .env copying (via worktree-manager.sh) or custom directory locations

Quick Reference¶

Situation	Action
`.worktrees/` exists	Use it (verify .gitignore)
`worktrees/` exists	Use it (verify .gitignore)
Both exist	Use `.worktrees/`
Neither exists	Check CLAUDE.md → Ask user
Directory not in .gitignore	Add it immediately + commit
Tests fail during baseline	Report failures + ask
No package.json/Cargo.toml	Skip dependency install

Common Mistakes¶

Skipping .gitignore verification - Problem: Worktree contents get tracked, pollute git status - Fix: Always grep .gitignore 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.)

Worktree dev-server fails on first start with 500 / connection errors - Problem: .env*.local files are gitignored and not propagated by git worktree add. The new worktree has no credentials, so any code reading process.env / os.environ gets undefined values. - Fix: Copy the file manually after the worktree is created and before starting the dev-server:

cp <source-repo>/.env.local <new-worktree>/.env.local

Symlinks (ln -s) also work but break if the source repo moves. The companion git-worktree skill's worktree-manager.sh automates .env* propagation if you prefer not to copy manually (see "When to use native flag vs manual setup" above).

⚠ Credential warning: these files contain secrets. If your worktree lives in ~/Library/CloudStorage/, ~/OneDrive*, ~/iCloud Drive/, ~/Dropbox/, or ~/Google Drive/, copying credentials there exposes them to the cloud sync. Avoid cloud-synced worktree locations for repos with secrets.

Example Workflow¶

You: I'm using the using-git-worktrees skill to set up an isolated workspace.

[Check .worktrees/ - exists]
[Verify .gitignore - contains .worktrees/]
[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 .gitignore verification (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 .gitignore 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 - Any skill needing isolated workspace

Pairs with: - finishing-a-development-branch - REQUIRED for cleanup after work complete - executing-plans or subagent-driven-development - Work happens in this worktree