/git-worktree

name: git-worktree
description: This skill manages Git worktrees for isolated parallel development. It handles creating, listing, switching, and cleaning up worktrees with a simple interactive interface, following KISS principles.

Git Worktree Manager

This skill provides a unified interface for managing Git worktrees across your development workflow. Whether you're reviewing PRs in isolation or working on features in parallel, this skill handles all the complexity.

What This Skill Does

• **Create worktrees** from main branch with clear branch names
• **List worktrees** with current status
• **Switch between worktrees** for parallel work
• **Clean up completed worktrees** automatically
• **Interactive confirmations** at each step
• **Automatic .gitignore management** for worktree 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: 1. Copies `.env`, `.env.local`, `.env.test`, etc. from main repo 2. Ensures `.worktrees` is in `.gitignore` 3. Creates consistent directory structure

# ✅ CORRECT - Always use the script
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/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

Use this skill in these scenarios:

1. **Code Review (`/workflows:review`)**: If NOT already on the target branch (PR branch or requested branch), offer worktree for isolated review 2. **Feature Work (`/workflows:work`)**: Always ask if user wants parallel worktree or live branch work 3. **Parallel Development**: When working on multiple features simultaneously 4. **Cleanup**: After completing work in a worktree

How to Use

In Claude Code Workflows

The skill is automatically called from `/workflows:review` and `/workflows:work` commands:

# For review: offers worktree if not on PR branch
# For work: always asks - new branch or worktree?

Manual Usage

You can also invoke the skill directly from bash:

# Create a new worktree (copies .env files automatically)
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login

# List all worktrees
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list

# Switch to a worktree
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh switch feature-login

# Copy .env files to an existing worktree (if they weren't copied)
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh copy-env feature-login

# Clean up completed worktrees
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup

Commands

`create <branch-name> [from-branch]`

Creates a new worktree with the given branch name.

**Options:**

• `branch-name` (required): The name for the new branch and worktree
• `from-branch` (optional): Base branch to create from (defaults to `main`)

**Example:**

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login

**What happens:** 1. Checks if worktree already exists 2. Updates the base branch from remote 3. Creates new worktree and branch 4. **Copies all .env files from main repo** (.env, .env.local, .env.test, etc.) 5. Shows path for cd-ing to the worktree

`list` or `ls`

Lists all available worktrees with their branches and current status.

**Example:**

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list

**Output shows:**

• Worktree name
• Branch name
• Which is current (marked with ✓)
• Main repo status

`switch <name>` or `go <name>`

Switches to an existing worktree and cd's into it.

**Example:**

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh switch feature-login

**Optional:**

• If name not provided, lists available worktrees and prompts for selection

`cleanup` or `clean`

Interactively cleans up inactive worktrees with confirmation.

**Example:**

bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup

**What happens:** 1. Lists all inactive worktrees 2. Asks for confirmation 3. Removes selected worktrees 4. Cleans up empty directories

Workflow Examples

Code Review with Worktree

# Claude Code recognizes you're not on the PR branch
# Offers: "Use worktree for isolated review? (y/n)"

# You respond: yes
# Script runs (copies .env files automatically):
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create pr-123-feature-name

# You're now in isolated worktree for review with all env vars
cd .worktrees/pr-123-feature-name

# After review, return to main:
cd ../..
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup

Parallel Feature Development

# For first feature (copies .env files):
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-login

# Later, start second feature (also copies .env files):
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh create feature-notifications

# List what you have:
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh list

# Switch between them as needed:
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh switch feature-login

# Return to main and cleanup when done:
cd .
bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh cleanup

Key Design Principles

KISS (Keep It Simple, Stupid)

• **One manager script** handles all worktree operations
• **Simple commands** with sensible defaults
• **Interactive prompts** prevent accidental operations
• **Clear naming** using branch