using-git-worktrees（使用 Git 工作树）

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.