| name | using-git-worktrees |
| description | Use when starting a new feature branch, creating isolated development environments, or working on multiple tasks simultaneously without stashing or switching branches. Triggers: user says "worktree", "new branch for work", "parallel development", "isolated environment", needs to work on two things at once.
|
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
| Condition | Action |
|---|
| Worktree for this branch already exists | Navigate to existing worktree |
CLAUDE.md has worktree-directory | 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 .gitignore |
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:
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
| Check | Result | Action |
|---|
Path inside repo, not in .gitignore | FAIL | Add to .gitignore 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
git worktree add <path> -b <branch-name> <base-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 |
|---|
pnpm-lock.yaml | Node.js (pnpm) | pnpm install |
yarn.lock | Node.js (yarn) | yarn install |
package-lock.json | Node.js (npm) | npm install |
package.json (no lock) | Node.js (npm) | npm install |
pyproject.toml + tool.poetry | Python (poetry) | poetry install |
pyproject.toml (no poetry) | Python (pip) | pip install -e . |
setup.py | Python (pip) | pip install -e . |
requirements.txt | Python (pip) | pip install -r requirements.txt |
go.mod | Go | go mod download |
Cargo.toml | Rust | cargo build |
Gemfile | Ruby | bundle install |
composer.json | PHP | composer install |
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:
cp .env.example .env
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:
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
git worktree remove <path>
git worktree remove --force <path>
git worktree prune
List All Worktrees
git worktree list
Handling Locked Worktrees
If a worktree is locked (to prevent accidental removal):
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 git worktree list first |
Worktree inside repo without .gitignore | Worktree files show as untracked | Add path to .gitignore |
| 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 | .env files are not shared between worktrees | Copy and configure .env |
| Leaving stale worktrees after merge | Disk waste, confusing git worktree list | 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 |
self-learning | Check CLAUDE.md for worktree directory preferences |
planning | 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.
