Git worktree management for isolated parallel development. Handles creating, listing, switching, and cleaning up worktrees with interactive confirmations, automatic .env copying, and .gitignore management. Follows KISS principles.
Git worktree management for isolated parallel development. Handles creating, listing, switching, and cleaning up worktrees with interactive confirmations, automatic .env copying, and .gitignore management. Follows KISS principles.
allowed-tools
Bash
argument-hint
[create|list|cleanup] [branch-name]
Current Worktrees
!git worktree list 2>/dev/null || echo "Not a git repository or git not available."
Git Worktree Manager
Unified interface for managing Git worktrees across your development workflow. Whether reviewing PRs in isolation or working on features in parallel, this skill handles all the complexity.
What This Skill Does
Create worktrees from a base branch with clear branch names
List worktrees with current status
Switch between worktrees for parallel work
Clean up completed worktrees automatically
Automatic .gitignore management for .worktrees/ directory
Automatic .env file copying from main repo to new worktrees
CRITICAL: Always Use the Manager Script
NEVER call git worktree add directly. Always use the worktree-manager.sh script.
The script handles critical setup that raw git commands don't:
Copies .env, .env.local, .env.test, etc. from main repo
Ensures .worktrees is in .gitignore
Creates consistent directory structure
# CORRECT - Always use the script
bash ${CLAUDE_SKILL_DIR}/scripts/worktree-manager.sh create feature-name
# WRONG - Never do this directly
git worktree add .worktrees/feature-name -b feature-name main
When to Use This Skill
Code Review (/blueprint-dev:bp:review): If NOT already on the target branch, offer worktree for isolated review
Feature Work (/blueprint-dev:bp:build): Ask if user wants parallel worktree or live branch work
Parallel Development: When working on multiple features simultaneously
Cleanup: After completing work in a worktree
Commands
create <branch-name> [from-branch]
Creates a new worktree with the given branch name.
branch-name (required): Name for the new branch and worktree
from-branch (optional): Base branch to create from (defaults to main)
1. Check current branch
2. If ALREADY on target branch → stay there, no worktree needed
3. If DIFFERENT branch → offer worktree:
"Use worktree for isolated review? (y/n)"
- yes → call git-worktree skill to create worktree
- no → proceed with PR diff on current branch
With /blueprint-dev:bp:build
1. Ask: "How do you want to work?"
1. New branch on current worktree (live work)
2. Worktree (parallel work)
2. If choice 1 → create new branch normally
3. If choice 2 → call git-worktree skill to create from main
Workflow Examples
Code Review with Worktree
# Create isolated worktree for review (copies .env files)
bash ${CLAUDE_SKILL_DIR}/scripts/worktree-manager.sh create pr-123-feature-name
cd .worktrees/pr-123-feature-name
# After review, return to main and clean upcd ../..
bash ${CLAUDE_SKILL_DIR}/scripts/worktree-manager.sh cleanup
Parallel Feature Development
# Start first feature
bash ${CLAUDE_SKILL_DIR}/scripts/worktree-manager.sh create feature-login
# Start second feature
bash ${CLAUDE_SKILL_DIR}/scripts/worktree-manager.sh create feature-notifications
# List and switch between them
bash ${CLAUDE_SKILL_DIR}/scripts/worktree-manager.sh list
bash ${CLAUDE_SKILL_DIR}/scripts/worktree-manager.sh switch feature-login
Key Design Principles
KISS (Keep It Simple)
One manager script handles all worktree operations
Simple commands with sensible defaults
Interactive prompts prevent accidental operations
Opinionated Defaults
Worktrees always created from main (unless specified)
Worktrees stored in .worktrees/ directory
Branch name becomes worktree name
.gitignore automatically managed
Safety First
Confirms before creating worktrees
Confirms before cleanup to prevent accidental removal
Won't remove current worktree
Clear error messages
Troubleshooting
"Worktree already exists"
The script will ask if you want to switch to it instead.
"Cannot remove worktree: it is the current worktree"
Switch out of the worktree first:
cd $(git rev-parse --show-toplevel)
bash ${CLAUDE_SKILL_DIR}/scripts/worktree-manager.sh cleanup
