git-worktree

Git Worktree Management

Overview

This skill provides comprehensive Git worktree management capabilities, enabling work on multiple branches simultaneously in isolated directories. Worktrees eliminate the need for stashing when switching contexts and are ideal for parallel development, quick bug fixes, and code reviews.

When to Use This Skill

Use this skill when the user wants to:

• Create a new worktree from a local branch, remote branch, or new branch
• List all active worktrees with detailed information
• Delete and clean up worktrees
• Get navigation commands to switch between worktrees
• Set up parallel development environments

How It Works

Configuration

Location Strategy: Sibling directory pattern

• Worktrees are created outside the main repository: ../<project>-<branch>
• Example: Main repo at ~/dev/myproject, worktree at ~/dev/myproject-feature-x
• Benefits: Clean separation, no nested repos, IDE-friendly

Naming Convention: <project>-<branch>

• Project name extracted using: basename "$(git rev-parse --show-toplevel)"
• Example: myproject-feature-auth, myapp-bugfix-login

Interface

Hybrid Mode: Accepts arguments when provided, prompts when missing

Usage patterns:

# Interactive menu
User: "Manage my worktrees"
User: "Create a worktree"

# Direct with arguments
User: "Create worktree from remote branch feature-x"
User: "List all worktrees"
User: "Delete worktree for branch hotfix-123"

Core Operations

1. List Worktrees

Purpose: Show all active worktrees with detailed information

What to display:

• Index number for easy reference
• Worktree path
• Branch name
• HEAD commit hash (short)
• Commit message (first line)
• Indicator for current worktree

Implementation:

# Get project name
project=$(basename "$(git rev-parse --show-toplevel)")

# List worktrees with details
git worktree list -v

Output format:

Git Worktrees for myproject:

1. /Users/dev/myproject (main)
   abc1234 Initial commit
   [CURRENT]

2. /Users/dev/myproject-feature-x (feature-x)
   def5678 Add authentication logic

3. /Users/dev/myproject-hotfix (hotfix-123)
   789abcd Fix login bug

2. Create Worktree from Remote Branch

Purpose: Fetch and create a worktree from a remote branch

Steps:

1. Validate we're in a git repository
2. Get project name: project=$(basename "$(git rev-parse --show-toplevel)")
3. Extract branch name from remote reference (e.g., origin/feature-x → feature-x)
4. Check if worktree already exists (warn and skip if it does)
5. Fetch remote branch: git fetch origin <branch-name>
6. Verify remote branch exists (check exit code)
7. Determine worktree path: ../<project>-<branch-name>
8. Create worktree: git worktree add ../<project>-<branch-name> origin/<branch-name>
9. Show success message with path and navigation command

Error handling:

• Not in git repo: Show clear error message
• Worktree already exists: "Worktree for branch 'X' already exists at Y. Use 'list' to see all worktrees."
• Remote branch doesn't exist: "Remote branch 'origin/X' not found. Available branches: [list]"

Success output:

✓ Created worktree for remote branch 'feature-x'

Location: /Users/dev/myproject-feature-x
Branch: feature-x (tracking origin/feature-x)

To switch to this worktree:
  cd ../myproject-feature-x

To start working:
  cd ../myproject-feature-x && code .

3. Create Worktree from Local Branch

Purpose: Create a worktree from an existing local branch

Steps:

1. Validate we're in a git repository
2. Get project name
3. Verify local branch exists: git rev-parse --verify <branch-name>
4. Check if worktree already exists
5. Create worktree: git worktree add ../<project>-<branch-name> <branch-name>
6. Show success message with navigation

Error handling:

• Local branch doesn't exist: "Local branch 'X' not found. Available branches: [list local branches]"
• Worktree already exists: Same as remote case

4. Create Worktree with New Branch

Purpose: Create a worktree with a brand new branch

Parameters needed:

• New branch name
• Base branch (optional, default: current branch)

Steps:

1. Validate we're in a git repository
2. Get project name
3. Get base branch (use current if not specified)
4. Check if worktree directory already exists
5. Create worktree with new branch: git worktree add -b <new-branch> ../<project>-<new-branch> <base-branch>
6. Show success message

Success output:

✓ Created new worktree with branch 'experiment-auth'

Location: /Users/dev/myproject-experiment-auth
Branch: experiment-auth (based on main)

To switch to this worktree:
  cd ../myproject-experiment-auth

5. Delete Worktree

Purpose: Remove a worktree and show prune command

Steps:

1. If no branch specified, list all worktrees for selection
2. Verify worktree exists for specified branch
3. Remove worktree: git worktree remove <path> or manually rm -rf <path>
4. Show manual prune command (don't auto-execute per user preference)

Output:

✓ Removed worktree at /Users/dev/myproject-feature-x

To clean up metadata, run:
  git worktree prune

6. Prune Worktrees

Purpose: Clean up worktree metadata

Steps:

1. Run: git worktree prune
2. Show what was cleaned

Output:

✓ Pruned stale worktree metadata

Run 'git worktree list' to see remaining worktrees.

7. Switch Helper

Purpose: Show easy navigation to worktrees

Implementation:

1. List all worktrees (numbered)
2. Provide copy-ready cd commands

Output:

Available worktrees:

1. main (current)
   cd /Users/dev/myproject

2. feature-x
   cd /Users/dev/myproject-feature-x

3. hotfix-123
   cd /Users/dev/myproject-hotfix

Interactive Flow

When invoked without arguments:

1. Show menu: ``` Git Worktree Management

1. List all worktrees
2. Create from remote branch
3. Create from local branch
4. Create new branch
5. Delete worktree
6. Prune metadata
7. Switch between worktrees ```

1. Prompt for selection
2. For create operations, prompt for required info (branch name, base branch, etc.)
3. Execute operation
4. Show results with clear next steps

Direct Command Parsing

When arguments are provided, parse intent:

• "list" → List operation
• "create remote <branch>" → Create from remote
• "create local <branch>" → Create from local
• "create new <branch> [from <base>]" → Create new branch
• "delete <branch>" → Delete worktree
• "prune" → Prune metadata
• "switch" → Switch helper

Error Handling Checklist

Before any operation:

• ✓ Verify in git repository: git rev-parse --git-dir
• ✓ Get project name successfully
• ✓ Validate branch exists (for remote/local operations)
• ✓ Check worktree doesn't already exist (for create operations)
• ✓ Provide actionable error messages with suggestions