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