git-worktrees

Git Worktrees

Create isolated workspaces for parallel development without disrupting current work.

Purpose

Git worktrees allow multiple branches to be checked out simultaneously in separate directories. This enables parallel work without stashing, context switching, or polluting the main workspace. This skill provides structured worktree creation with safety verification.

Integration

Called by

• implementing-plans - Offers worktree isolation before implementation
• User directly via /rpikit:git-worktrees

Pairs with

• finishing-work - Handles worktree cleanup after implementation
• writing-plans - Plans may specify worktree isolation for high-stakes changes

When to Use

Use worktrees when:

• Starting feature work that shouldn't affect main workspace
• Working on multiple features in parallel
• Testing changes in isolation
• Running long processes while continuing other work
• Reviewing PRs without disrupting current work

Skip worktrees when:

• Quick single-file fixes
• Changes that don't need isolation
• The main workspace is already clean

Directory Selection Priority

When creating worktrees, check these locations in order:

1. Check for Existing Worktree Directory

Look for:
- .worktrees/ (hidden, preferred)
- worktrees/ (visible)

If both exist, prefer .worktrees/

2. Check Project Configuration

Look in CLAUDE.md or project documentation for:
- Stated worktree location preference
- Project-specific conventions

3. Ask the User

If no preference found:

"Where should worktrees be created?"
- .worktrees/ (project-local, recommended, must be in .gitignore)
- worktrees/ (project-local, visible, must be in .gitignore)
- External location (e.g., ~/worktrees/project-name/)

Safety Verification

Critical for project-local worktrees:

Before creating a worktree in .worktrees/ or worktrees/, verify the specific directory you're using is ignored:

# For .worktrees/ (check returns 0 if ignored)
git check-ignore -q .worktrees

# For worktrees/ (check returns 0 if ignored)
git check-ignore -q worktrees

If the command returns exit code 0, the directory is properly ignored.

If NOT ignored:

1. Add to .gitignore
   echo ".worktrees/" >> .gitignore
   (or "worktrees/" depending on choice)

2. Commit the change
   git add .gitignore
   git commit -m "Add worktree directory to .gitignore"

3. Then proceed with worktree creation

Why this matters: Accidentally committing worktree contents creates massive, confusing commits with duplicate code.

Quick Reference

Situation	Action
.worktrees/ exists and is ignored	Use it
worktrees/ exists and is ignored	Use it
Neither exists	Create .worktrees/, add to .gitignore, commit
Directory exists but not ignored	Add to .gitignore first, commit, then proceed
Baseline tests fail	Investigate before proceeding (may need deps/config)

Worktree Creation Process

Step 1: Detect Project Information

Get project name: basename $(git rev-parse --show-toplevel)
Get current branch: git branch --show-current
Get default branch: git symbolic-ref refs/remotes/origin/HEAD

Step 2: Create Worktree

For new feature branch:

git worktree add <worktree-path> -b <branch-name>

For existing branch:

git worktree add <worktree-path> <existing-branch>

From specific base:

git worktree add <worktree-path> -b <branch-name> origin/main

Step 3: Auto-Detect and Run Setup

Detect project type and run appropriate setup:

If package.json exists:
  npm install (or yarn, pnpm based on lockfile)

If Cargo.toml exists:
  cargo build

If requirements.txt exists:
  pip install -r requirements.txt (in venv if present)

If Gemfile exists:
  bundle install

If go.mod exists:
  go mod download

Step 4: Run Baseline Tests

Verify clean state before starting work:

# Run project test command
npm test / cargo test / pytest / etc.

If tests fail:

"Baseline tests fail in the new worktree.

This could mean:
- Missing dependencies
- Environment configuration needed
- Pre-existing failures on the base branch

Options:
- Investigate and fix (recommended)
- Proceed anyway (acknowledge failures exist)
- Abort worktree creation"

Step 5: Report Ready State

"Worktree created and ready:

Location: <worktree-path>
Branch: <branch-name>
Base: <base-branch>
Tests: <pass/fail status>

To work in this worktree:
cd <worktree-path>

To return to main workspace:
cd <main-repo-path>"

Worktree Management

List Worktrees

git worktree list

Remove Worktree

# From main repository
git worktree remove <worktree-path>

# If worktree has changes, force removal
git worktree remove --force <worktree-path>

Prune Stale Worktrees

# Remove worktrees whose directories no longer exist
git worktree prune

Integration with RPI Workflow

With Plan Phase

When planning involves isolated implementation:

Plan approved
→ Create worktree for implementation
→ Run setup in worktree
→ Verify baseline tests
→ Begin implementation in isolated environment

With Finishing Work

After implementation in worktree:

Implementation complete
→ Use finishing-work skill
→ If merging locally: cleanup worktree
→ If creating PR: keep worktree for review cycle
→ If discarding: cleanup worktree

External vs Project-Local Worktrees

Project-Local (in .worktrees/ or worktrees/)

Pros:

• Everything in one place
• Easy to find related work
• Cleans up with project deletion

Cons:

• Must ensure directory is gitignored
• Uses project disk space

External (e.g., ~/worktrees/project-name/)

Pros:

• No gitignore management needed
• Separate from project structure
• Can survive project directory changes

Cons:

• Scattered across filesystem
• May forget to clean up

Never Do These

• Create project-local worktree without verifying gitignore - Run git check-ignore first
• Skip dependency installation - Always run npm install / cargo build / etc.
• Skip baseline tests - Verify tests pass before starting work
• Proceed when baseline tests fail - Investigate failures before continuing
• Use ambiguous worktree location - Ask user preference, default to .worktrees/
• Skip reading CLAUDE.md - Check for project-specific worktree conventions
• Leave stale worktrees - Remove after work is merged or abandoned
• Overuse worktrees - Reserve for substantial, isolated work, not small fixes

Cleanup Checklist

Before removing a worktree:

• Work is merged or intentionally abandoned
• No uncommitted changes (or explicitly discarded)
• Branch is deleted (if work was merged)
• No running processes in the worktree

Example Workflow

User: Create a worktree for implementing the new auth feature
Assistant: I will create a worktree for the auth feature.

[Checks for existing .worktrees/ directory]
[Runs: git check-ignore -q .worktrees]
[Exit code 0 - directory is ignored]

Creating worktree at .worktrees/auth-feature...
[Runs: git worktree add .worktrees/auth-feature -b auth-feature origin/main]

Installing dependencies...
[Detects package.json, runs: npm install]

Running baseline tests...
[Runs: npm test]
All tests pass.

Worktree created and ready:
Location: .worktrees/auth-feature
Branch: auth-feature
Base: origin/main
Tests: passing

Commands Reference

# Create worktree with new branch
git worktree add <path> -b <new-branch> <base>

# Create worktree with existing branch
git worktree add <path> <existing-branch>

# List all worktrees
git worktree list

# Remove worktree
git worktree remove <path>

# Force remove (with uncommitted changes)
git worktree remove --force <path>

# Prune stale entries
git worktree prune