Using Git Worktrees

Overview

Create isolated workspaces sharing the same repository for parallel branch work. Follow systematic directory selection and safety verification to ensure reliable isolation.

Violating the letter of the rules is violating the spirit of the rules. Skipping safety verification "just this once" or assuming directory locations are the most common causes of worktree problems.

When to Use

• Starting feature work requiring isolation from current workspace

• Working on multiple branches simultaneously

• Executing implementation plans in a clean environment (OPTIONAL: pairs with humaninloop:plan )

• Testing changes without affecting the main working directory

• Parallel code review while continuing development

When NOT to Use

• Single-branch workflows: No need for isolation when working linearly

• Quick fixes on current branch: Worktrees add overhead for simple changes

• Non-git repositories: Worktrees are git-specific

• Temporary experiments: A simple branch may suffice

• When disk space is constrained: Each worktree duplicates working files

Red Flags - STOP and Restart Properly

If any of these thoughts arise, STOP immediately:

• "The directory is probably already ignored"

• "I know where worktrees go in this project"

• "Tests are slow, I'll skip baseline verification"

• "This is a simple project, safety checks are overkill"

• "User wants to start quickly, I'll verify later"

• "I've done this before, I can skip the priority order"

All of these mean: Rationalization is occurring. Restart with proper process.

Common Rationalizations

Excuse Reality

"Directory is probably ignored" Probably =/= verified. One git check-ignore command takes seconds. Always verify.

"I know where worktrees go here" Knowledge =/= following process. Check existing directories, then CLAUDE.md, then ask.

"Tests are slow" Slow tests =/= skip tests. Baseline verification prevents hours of debugging wrong baseline.

"Simple project" Simple projects have caused the biggest worktree pollution. Process exists because of them.

"Will verify later" Later rarely comes. Worktree contents in git history are permanent mistakes. Do it now.

"User seems impatient" Impatience is not permission. Explain why verification matters.

Core Process

Step 1: Directory Selection

Follow this priority order strictly:

1.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 takes precedence.

1.2 Check CLAUDE.md Configuration

grep -i "worktree.*director" CLAUDE.md 2>/dev/null

If a preference is specified, use it without asking.

1.3 Ask User

Only when no directory exists AND no CLAUDE.md preference:

No worktree directory found. Where should worktrees be created?

1. .worktrees/ (project-local, hidden)
2. ~/worktrees/<project-name>/ (global location)

Which is preferred?

No exceptions:

• Not for "obvious" projects

• Not for "standard" setups

• Not when "everyone uses .worktrees"

• Not even if user says "just use the usual place"

Step 2: Safety Verification

For project-local directories (.worktrees or worktrees):

MUST verify directory is ignored before creating worktree:

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

• Add appropriate line to .gitignore

• Commit the change: git add .gitignore && git commit -m "chore: add worktree directory to gitignore"

• Proceed with worktree creation

Why critical: Prevents accidentally committing worktree contents to repository. Worktree contents in git history cannot be fully removed without history rewriting.

For global directories (e.g., ~/worktrees):

No gitignore verification needed - outside project entirely.

No exceptions:

• Not for "I'm pretty sure it's already ignored"

• Not for "this repo has good gitignore defaults"

• Not when "I'll check after creating the worktree"

• Not even for "the user said don't worry about it"

Step 3: Create Worktree

Get project name

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

Determine full path based on location type

For project-local:

path=".worktrees/$BRANCH_NAME"

For global:

path="$HOME/worktrees/$project/$BRANCH_NAME"

Create worktree with new branch

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

Step 4: Run Project Setup

Auto-detect and run appropriate setup commands:

File Setup Command

package.json

npm install or yarn install or pnpm install

Cargo.toml

cargo build

requirements.txt

pip install -r requirements.txt

pyproject.toml

poetry install or pip install -e .

go.mod

go mod download

Gemfile

bundle install

Skip setup only if no recognizable project file exists.

Step 5: Verify Clean Baseline

Run tests to ensure worktree starts clean:

Use project-appropriate command

npm test # Node.js cargo test # Rust pytest # Python go test ./... # Go bundle exec rspec # Ruby

If tests fail: Report failures with details. Ask whether to proceed or investigate.

If tests pass: Report success with test count.

If no test command available: Note this and proceed, but warn that baseline is unverified.

No exceptions:

• Not for "tests are slow, user wants to start"

• Not for "I ran tests recently in the main worktree"

• Not when "this is a simple feature, baseline doesn't matter"

• Not even for "user explicitly asked to skip testing"

Step 6: Report Completion

Worktree ready at <full-path> Branch: <branch-name> Tests: <N> passing, 0 failures (or "no test suite detected") Ready to implement <feature-name>

After implementation is complete, follow the cleanup workflow in the Multi-Worktree Management section.

Quick Reference

Situation Action

.worktrees/ exists Use it (verify ignored first)

worktrees/ exists Use it (verify ignored first)

Both exist Use .worktrees/

Neither exists Check CLAUDE.md, then ask user

Directory not ignored Add to .gitignore, commit, then proceed

Tests fail during baseline Report failures, ask before proceeding

No package manager file Skip dependency install, note it

No test suite Proceed with warning about unverified baseline

Common Mistakes

Mistake Problem Fix

Skipping ignore verification Worktree contents get tracked, pollute git status, potentially committed Always run git check-ignore for project-local directories

Assuming directory location Creates inconsistency, violates project conventions Follow priority: existing > CLAUDE.md > ask

Proceeding with failing tests Cannot distinguish new bugs from pre-existing issues Report failures, get explicit permission

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

Skipping user prompt Creates worktrees where user does not want them When ambiguous, always ask

Error Recovery

Worktree Creation Fails

Error Cause Resolution

fatal: '<path>' already exists

Directory exists from previous attempt Remove directory: rm -rf <path> , then retry

fatal: '<branch>' is already checked out

Branch active in another worktree Use different branch name or remove existing worktree

fatal: not a git repository

Not in a git repo Navigate to git repository root first

fatal: invalid reference

Base branch doesn't exist Verify branch name, fetch from remote if needed

Recovery Steps

• Check worktree state: git worktree list

• Identify stuck entries: Look for paths that no longer exist

• Prune stale entries: git worktree prune

• Force remove if needed: git worktree remove --force <path>

Locked Worktrees

If a worktree shows as locked:

Check lock status

git worktree list --porcelain | grep -A1 locked

Unlock (only if certain no process is using it)

git worktree unlock <path>

Multi-Worktree Management

Listing Active Worktrees

git worktree list

Output:

/path/to/main abc1234 [main]

/path/to/.worktrees/feature-a def5678 [feature-a]

/path/to/.worktrees/feature-b ghi9012 [feature-b]

Switching Between Worktrees

Each worktree is independent. Simply cd to the desired worktree path. No checkout or stash required.

Cleanup Workflow

After branch is merged or abandoned:

1. Return to main worktree

cd /path/to/main

2. Remove the worktree

git worktree remove .worktrees/feature-name

3. Delete the branch (if merged)

git branch -d feature-name

4. Prune any stale references

git worktree prune

For comprehensive cleanup after feature completion, follow the steps above.

Disk Space Considerations

Each worktree duplicates working files (not git objects). Monitor disk usage:

Check worktree sizes

du -sh .worktrees/*

Remove largest/oldest worktrees first when space constrained

Reference Commands

List all worktrees

git worktree list

Create worktree with new branch

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

Create worktree from existing branch

git worktree add <path> <existing-branch>

Remove a worktree

git worktree remove <path>

Force remove (uncommitted changes)

git worktree remove --force <path>

Prune stale worktree entries

git worktree prune

Lock worktree (prevent accidental removal)

git worktree lock <path>

Unlock worktree

git worktree unlock <path>

Example Scripts

Working shell scripts are available in examples/ :

• examples/worktree-setup.sh - Complete worktree creation with safety checks

• examples/worktree-cleanup.sh - Safe removal with uncommitted change detection

• examples/worktree-list.sh - Enhanced listing with status and disk usage