Using Git Worktrees

Using Git Worktrees

Overview

Create isolated working directories for parallel development tasks using git worktree, allowing multiple branches to be checked out simultaneously without conflicts. This skill enforces a deterministic, multi-phase process from directory selection through setup verification, ensuring every worktree is production-ready before any work begins.

When to Use

• Starting a new feature branch that should not interfere with current work
• Working on multiple tasks simultaneously (bug fix + feature)
• Creating a clean environment for testing or code review
• Running long processes (tests, builds) while continuing development

Phase 1: Select Worktree Directory

[HARD-GATE] Do NOT skip directory selection. Do NOT assume a default path without checking priorities.

Follow this priority order exactly:

Priority 1: Existing Worktree Matching Task

Check if a worktree already exists for the task:

git worktree list

If a matching worktree exists, use it. Do NOT create a duplicate.

Priority 2: CLAUDE.md Worktree Directory Hint

Check the project's CLAUDE.md for a configured worktree directory:

# Example CLAUDE.md entry
worktree-directory: ../worktrees

If specified, create worktrees under that directory.

Priority 3: Ask the User

If no hint is configured and no convention is obvious, ask the user where worktrees should be created. Suggest a sensible default:

../worktrees/<project-name>/<branch-name>

STOP — Confirm the worktree directory with the user before proceeding.

Directory Selection Decision Table

Phase 2: Safety Verification

[HARD-GATE] Do NOT create any worktree until all safety checks pass.

Check .gitignore Coverage

If the worktree directory is inside the repository root, ensure it is in .gitignore:

# Check if the worktree path would be tracked
git check-ignore <worktree-path>

If not ignored, warn the user and suggest adding it to .gitignore.

Verify Clean Working Tree

Check for uncommitted changes that could cause issues:

git status --porcelain

If the working tree is dirty, inform the user and ask how to proceed:

• Commit changes first
• Stash changes
• Proceed anyway (worktree creation itself is safe)

Verify Branch Does Not Exist in Another Worktree

git worktree list

A branch cannot be checked out in two worktrees simultaneously. If the branch is already checked out, navigate to that existing worktree instead.

Safety Check Decision Table

Phase 3: Create the Worktree

# For a new branch
git worktree add <path> -b <branch-name> <base-branch>

# For an existing branch
git worktree add <path> <existing-branch>

Always tell the user the full path where the worktree was created:

Worktree created at: /absolute/path/to/worktree
Branch: feature/my-feature
Base: main

STOP — Confirm the worktree was created successfully before proceeding to setup.

Phase 4: Project Setup and Auto-Detection

After creating the worktree, detect and run the project's setup commands.

Setup Detection Decision Table

Multiple Ecosystems

If the project uses multiple ecosystems (e.g., a Go backend with a Node.js frontend), run setup for each detected ecosystem in the appropriate subdirectories.

Environment Files

If the project has .env.example or .env.template:

# Copy environment template if .env does not exist in worktree
cp .env.example .env  # then inform user to update values

Phase 5: Clean Baseline Test Verification

[HARD-GATE] Do NOT proceed with any work until baseline tests pass or failures are acknowledged.

Run the project's test suite to establish a clean baseline BEFORE starting any work:

# Use the project's test command
# Node.js: npm test / yarn test / pnpm test
# Python: pytest / python -m pytest
# Go: go test ./...
# Rust: cargo test

Purpose:

• Confirms the worktree is set up correctly
• Establishes that all tests pass before changes are made
• Any test failures after this point are caused by your changes, not pre-existing issues

If baseline tests fail:

• Report the failures to the user
• Do NOT proceed with work until the baseline is understood
• The base branch may have broken tests that need addressing first

Phase 6: Location Reporting

Always report the worktree location clearly to the user:

Worktree ready:
  Path:    /Users/dev/worktrees/myproject/feature-auth
  Branch:  feature/auth-refactor
  Base:    main
  Setup:   npm install (completed)
  Tests:   24 passed, 0 failed

Cleanup Patterns

After Merging or Completing Work

# Remove the worktree
git worktree remove <path>

# If files remain (dirty worktree), force removal
git worktree remove --force <path>

# Prune stale worktree references
git worktree prune

List All Worktrees

git worktree list

Handling Locked Worktrees

If a worktree is locked (to prevent accidental removal):

# Unlock before removing
git worktree unlock <path>
git worktree remove <path>

Anti-Patterns / Common Mistakes

Integration Points

Skill Type

RIGID — Follow this process exactly. Every phase must be completed in order. Do NOT skip safety checks. Do NOT skip baseline test verification. Do NOT create worktrees without confirming the directory.