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 ring:using-git-worktrees skill to set up an isolated workspace."

Directory Selection Process

Priority order: (1) Existing .worktrees/ or worktrees/ (2) CLAUDE.md preference (3) Ask user

ls -d .worktrees worktrees 2>/dev/null # Check existing (prefer .worktrees) grep -i "worktree.*director" CLAUDE.md # Check project preference

If none found, ask: .worktrees/ (project-local, hidden) OR ~/.config/ring/worktrees/<project>/ (global)

Safety Verification

Project-local directories: MUST verify .gitignore before creating: grep -q "^.worktrees/$|^worktrees/$" .gitignore

• If NOT in .gitignore: Add it → commit → proceed (fix broken things immediately)

• Why critical: Prevents accidentally committing worktree contents

Global directory (~/.config/ring/worktrees): No verification needed - outside project.

Creation Steps

1. Detect project

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

2. Create worktree (path = $LOCATION/$BRANCH or ~/.config/ring/worktrees/$project/$BRANCH)

git worktree add "$path" -b "$BRANCH_NAME" && cd "$path"

3. Auto-detect and run setup

[ -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 (npm test / cargo test / pytest / go test ./...)

If tests fail: Report failures, ask whether to proceed or investigate. If tests pass: Report: Worktree ready at <path> | Tests passing (<N> tests) | Ready to implement <feature>

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

Mistake Problem Fix

Skip .gitignore verification Worktree contents tracked, pollute git status Always grep .gitignore first

Assuming directory location Inconsistency, violates conventions Follow priority: existing > CLAUDE.md > ask

Proceeding with failing tests Can't distinguish new vs pre-existing bugs Report failures, get permission

Hardcoding setup commands Breaks on different tools Auto-detect from project files

Example Workflow

Announce → Check .worktrees/ exists → Verify .gitignore → git worktree add .worktrees/auth -b feature/auth → npm install → npm test (47 passing) → Report ready

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

• ring:executing-plans or ring:subagent-driven-development - Work happens in this worktree

Blocker Criteria

STOP and report if:

Decision Type Blocker Condition Required Action

.gitignore Safety Project-local worktree directory not in .gitignore STOP and report

Baseline Tests Tests fail during worktree setup STOP and report

Directory Ambiguity Multiple conflicting worktree locations exist STOP and report

Permission Issues Cannot create worktree in target directory STOP and report

Cannot Be Overridden

The following requirements CANNOT be waived:

• Project-local worktree directories MUST be in .gitignore before creation

• Baseline test verification is REQUIRED before proceeding with work

• Directory selection MUST follow priority order: existing > CLAUDE.md > ask user

• Worktree creation MUST include dependency installation and test verification

Severity Calibration

Severity Condition Required Action

CRITICAL Worktree directory not in .gitignore (project-local) MUST add to .gitignore immediately

CRITICAL Proceeding with failing baseline tests MUST report failures and get permission

HIGH Skipping dependency installation step MUST run appropriate package manager

HIGH Assuming directory location when ambiguous MUST follow priority order or ask user

MEDIUM Missing CLAUDE.md check in priority order Should check CLAUDE.md preferences

LOW Not auto-detecting project type Fix in next iteration

Pressure Resistance

User Says Your Response

"Skip .gitignore check, just create the worktree" "CANNOT skip .gitignore verification for project-local directories. Worktree contents would pollute git status."

"Tests are failing but proceed anyway" "CANNOT proceed with failing baseline tests. I need to report failures so we can distinguish pre-existing bugs from new ones."

"Put the worktree in this custom location" "I'll verify that location doesn't conflict with existing conventions and check .gitignore requirements first."

"Skip dependency installation, it takes too long" "CANNOT skip dependency installation. Tests won't run correctly without dependencies, invalidating baseline verification."

Anti-Rationalization Table

Rationalization Why It's WRONG Required Action

".gitignore check is paranoia" Without it, worktree contents get tracked, polluting every git status. MUST verify .gitignore first

"I know where worktrees go in this project" Assumption conflicts with existing directories or CLAUDE.md preferences. MUST follow directory priority order

"Failing tests are probably unrelated" You cannot distinguish new vs pre-existing bugs without clean baseline. MUST report failures and ask before proceeding

"Setup is straightforward, skip auto-detection" Different projects use different tools. Manual setup misses dependencies. MUST auto-detect from project files

"Global directory doesn't need verification" Global directories don't need .gitignore verification - this is correct. Only project-local needs it. MUST distinguish global vs project-local