Using Git Worktrees
Overview
Create isolated working directories for parallel development tasks using
, 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:
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
| Condition | Action |
|---|
| Worktree for this branch already exists | Navigate to existing worktree |
| CLAUDE.md has | Use configured path |
| Project has existing worktrees | Use same parent directory pattern |
| No convention found | Ask user, suggest ../worktrees/<project>/<branch>
|
| User specifies path inside repo root | Warn — must add to |
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
:
bash
# Check if the worktree path would be tracked
git check-ignore <worktree-path>
If not ignored, warn the user and suggest adding it to
.
Verify Clean Working Tree
Check for uncommitted changes that could cause issues:
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
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
| Check | Result | Action |
|---|
| Path inside repo, not in | FAIL | Add to first |
| Branch already in another worktree | FAIL | Use existing worktree |
| Working tree dirty | WARN | Inform user, ask preference |
| Path already exists (not worktree) | FAIL | Choose different path |
| All checks pass | PASS | Proceed to Phase 3 |
Phase 3: Create the Worktree
bash
# 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
| Indicator File | Ecosystem | Setup Command |
|---|
| Node.js (pnpm) | |
| Node.js (yarn) | |
| Node.js (npm) | |
| (no lock) | Node.js (npm) | |
| + | Python (poetry) | |
| (no poetry) | Python (pip) | |
| Python (pip) | |
| Python (pip) | pip install -r requirements.txt
|
| Go | |
| Rust | |
| Ruby | |
| PHP | |
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
bash
# 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:
bash
# 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
bash
# 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
Handling Locked Worktrees
If a worktree is locked (to prevent accidental removal):
bash
# Unlock before removing
git worktree unlock <path>
git worktree remove <path>
Anti-Patterns / Common Mistakes
| Anti-Pattern | Why It Is Wrong | What to Do Instead |
|---|
| Creating duplicate worktree for same branch | Git does not allow it; wastes time | Check first |
| Worktree inside repo without | Worktree files show as untracked | Add path to |
| Skipping dependency install in worktree | Build/test failures from missing deps | Always run project setup |
| Skipping baseline test run | Cannot distinguish pre-existing vs new failures | Run tests before starting work |
| Assuming worktree has same env vars | files are not shared between worktrees | Copy and configure |
| Leaving stale worktrees after merge | Disk waste, confusing | Remove worktrees after branch completion |
| Force-removing worktree with uncommitted work | Permanent data loss | Commit or stash first |
Integration Points
| Skill | Integration |
|---|
finishing-a-development-branch
| After completing work in a worktree, use this to merge or create a PR |
dispatching-parallel-agents
| Run agents in separate worktrees for true isolation |
verification-before-completion
| Validate work before leaving the worktree |
| Check CLAUDE.md for worktree directory preferences |
| Worktree creation is often the first step of plan execution |
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.