gh-claudeforge-marketplace-plugins-commands-create-worktrees/commands/create-worktrees.md

allowed-tools, description

allowed-tools	description
Bash, Read, Write, Edit, Grep, Glob	Create and manage Git worktrees for parallel development and efficient branch management

Create Worktrees Command

Set up Git worktrees to work on multiple branches simultaneously without switching contexts.

Usage

/create-worktrees <branch_name> [base_branch] [path]

Examples:

/create-worktrees feature/new-auth                    # Create worktree for new branch
/create-worktrees hotfix/security-patch main         # Create from main branch
/create-worktrees feature/api-v2 develop ../worktrees/api-v2  # Custom path

What This Command Does

Creates Git worktrees that allow you to:

1. Work on Multiple Branches: Switch between features without stashing
2. Parallel Development: Build/test different branches simultaneously
3. PR Reviews: Check out PRs without affecting main work
4. Hotfix Management: Work on urgent fixes while continuing feature work
5. Efficient Testing: Compare changes across branches easily

Git Worktrees Explained

A worktree is a linked working directory that shares the same Git repository:

project/
├── .git/                    # Main repository
├── src/                     # Main branch
└── ../worktrees/
    ├── feature-a/          # Worktree for feature-a branch
    ├── feature-b/          # Worktree for feature-b branch
    └── pr-123/             # Worktree for PR review

Benefits:

• No need to stash changes when switching branches
• Run tests on multiple branches simultaneously
• Keep builds for different branches ready
• Review PRs without disrupting current work

Creating Worktrees

Basic Worktree Creation

# Create worktree for new branch
git worktree add ../worktrees/feature-xyz -b feature/xyz

# Create from existing branch
git worktree add ../worktrees/hotfix origin/hotfix/security

# Create from specific commit
git worktree add ../worktrees/test-v1 abc123

Recommended Workflow

Step 1: Create Worktree

# Create worktree directory structure
mkdir -p ../worktrees

# Add worktree for new feature
git worktree add ../worktrees/feature-auth -b feature/user-auth

# Navigate to worktree
cd ../worktrees/feature-auth

Step 2: Work in Worktree

# Make changes
vim src/auth/login.js

# Commit normally
git add .
git commit -m "Add user authentication"
git push -u origin feature/user-auth

Step 3: List Worktrees

git worktree list
# Output:
# /path/to/project              abc123 [main]
# /path/to/worktrees/feature-auth  def456 [feature/user-auth]

Common Use Cases

1. PR Review Workflow

Review pull requests without affecting your current work:

# Fetch PR branch
gh pr checkout 123

# Or manually
git fetch origin pull/123/head:pr-123
git worktree add ../worktrees/pr-123 pr-123

# Review the code
cd ../worktrees/pr-123
npm install
npm test
npm run build

# Return to your work
cd ../../project

2. Multi-Feature Development

Work on multiple features simultaneously:

# Feature A
git worktree add ../worktrees/feature-a -b feature/payment-gateway
cd ../worktrees/feature-a
npm install
npm run dev # Runs on port 3000

# Feature B (in another terminal)
cd /path/to/project
git worktree add ../worktrees/feature-b -b feature/notification-system
cd ../worktrees/feature-b
npm install
PORT=3001 npm run dev # Runs on port 3001

3. Hotfix While Developing

Handle urgent fixes without stashing feature work:

# You're working on a feature
cd /path/to/worktrees/feature-dashboard

# Urgent hotfix needed
cd /path/to/project
git worktree add ../worktrees/hotfix-urgent -b hotfix/security-patch main
cd ../worktrees/hotfix-urgent

# Fix the issue
vim src/security/validator.js
git add .
git commit -m "Fix security vulnerability"
git push -u origin hotfix/security-patch

# Create PR for hotfix
gh pr create --title "Security patch" --base main

# Return to feature work
cd ../feature-dashboard

4. Testing Across Branches

Compare behavior across different branches:

# Main branch
cd /path/to/project
npm test

# Feature branch
cd ../worktrees/feature-new-api
npm test

# Compare results side by side

Managing Worktrees

List Worktrees

# List all worktrees
git worktree list

# Detailed view
git worktree list --porcelain

Remove Worktrees

# Remove worktree (safe - checks for uncommitted changes)
git worktree remove ../worktrees/feature-completed

# Force remove (use with caution)
git worktree remove --force ../worktrees/abandoned-feature

# Or manually delete and prune
rm -rf ../worktrees/old-feature
git worktree prune

Clean Up Stale Worktrees

# Show stale worktrees
git worktree prune --dry-run

# Remove stale references
git worktree prune

Advanced Techniques

Batch Create Worktrees for PRs

# Create worktrees for multiple PRs
gh pr list --json number,headRefName --limit 5 | \
  jq -r '.[] | "\(.number) \(.headRefName)"' | \
  while read -r pr_num branch; do
    git worktree add "../worktrees/pr-$pr_num" "$branch" 2>/dev/null || \
      git worktree add "../worktrees/pr-$pr_num" -b "$branch" "origin/$branch"
  done

Worktree with Environment Setup

# Create worktree with automatic setup
create_worktree_with_setup() {
  local branch=$1
  local path="../worktrees/$branch"

  git worktree add "$path" -b "$branch"
  cd "$path"

  # Setup environment
  npm install
  cp ../.env.example .env

  # Run initial build
  npm run build

  echo "Worktree ready: $path"
}

create_worktree_with_setup "feature/new-feature"

Shared Build Cache

Optimize build times by sharing node_modules:

# Symbolic link to shared node_modules
cd ../worktrees/feature-a
ln -s ../../project/node_modules node_modules

Best Practices

1. Organize Worktrees

Keep worktrees in a dedicated directory:

project/
├── .git/
├── src/
└── ../worktrees/
    ├── features/
    │   ├── auth/
    │   └── dashboard/
    ├── hotfixes/
    │   └── security-patch/
    └── reviews/
        ├── pr-123/
        └── pr-124/

2. Naming Conventions

Use consistent naming:

• Features: feature-{name}
• Hotfixes: hotfix-{issue}
• PRs: pr-{number}
• Tests: test-{scenario}

3. Clean Up Regularly

Remove merged worktrees:

# After PR is merged
git worktree remove ../worktrees/feature-completed
git branch -d feature/completed
git push origin --delete feature/completed

4. Documentation

Track worktrees in your project:

# Create worktree registry
echo "# Active Worktrees" > .worktrees.md
git worktree list >> .worktrees.md

Common Issues & Solutions

Issue: "Already checked out"

# Error: branch is already checked out
# Solution: Use a worktree or checkout in different location
git worktree add --detach ../worktrees/temp
cd ../worktrees/temp
git checkout feature/branch

Issue: "Worktree path exists"

# Error: directory already exists
# Solution: Remove existing directory
rm -rf ../worktrees/old-path
git worktree add ../worktrees/old-path -b new-branch

Issue: Missing dependencies

# Each worktree needs its own node_modules
cd ../worktrees/new-feature
npm install

# Or use shared cache (use with caution)
npm ci --cache ../cache

Performance Tips

1. Limit Active Worktrees: Keep 3-5 active worktrees max
2. Share Git Objects: Worktrees share the .git directory automatically
3. Exclude from Backup: Add worktrees directory to backup exclusions
4. Use Shallow Clones: For temporary review worktrees
5. Clean Up Regularly: Remove merged or abandoned worktrees

Safety Guidelines

1. Always commit before removing: Ensure no uncommitted changes
2. Check worktree status: Use git worktree list before operations
3. Avoid nested worktrees: Don't create worktrees inside worktrees
4. Backup important work: Push branches before removing worktrees
5. Use prune carefully: Run git worktree prune --dry-run first

Integration with IDEs

VS Code

# Open worktree in new window
code ../worktrees/feature-auth

# Or add to workspace
code --add ../worktrees/feature-auth

JetBrains IDEs

# Open worktree as new project
idea ../worktrees/feature-auth

Methodology

Git worktrees enable efficient parallel development by:

• Context Preservation: Keep each branch's build and state separate
• Quick Switching: Move between branches instantly (just cd)
• Parallel Builds: Test multiple configurations simultaneously
• Safe Experimentation: Isolated environments for each branch
• Efficient Reviews: Check PRs without disrupting current work