Git Worktrees Skill

Description

This skill manages git worktrees — the ability to check out multiple branches simultaneously in separate directories. Perfect for working on a hotfix while a feature is in progress, or running tests on one branch while developing on another.

Instructions

When the user needs to work on multiple branches simultaneously, use git worktrees:

Creating a Worktree

Copy
# Create a worktree for a new branch
git worktree add ../project-hotfix -b hotfix/critical-bug

# Create a worktree for an existing branch
git worktree add ../project-feature feature/dashboard

# Create a worktree from a specific commit/tag
git worktree add ../project-v2 v2.0.0

# List all worktrees
git worktree list
# /Users/dev/project          abc1234 [main]
# /Users/dev/project-hotfix   def5678 [hotfix/critical-bug]
# /Users/dev/project-feature  ghi9012 [feature/dashboard]

Safe Worktree Workflow

Copy
# Step 1: Verify clean state
git status --short
# If dirty, commit or stash first

# Step 2: Create worktree
git worktree add ../project-hotfix -b hotfix/fix-auth

# Step 3: Work in the new worktree
cd ../project-hotfix
npm install  # Install deps (node_modules is per-worktree)
# ... make changes ...
git add -A && git commit -m "fix: resolve auth token expiry"
git push origin hotfix/fix-auth

# Step 4: Return to main worktree
cd ../project

# Step 5: Clean up when done
git worktree remove ../project-hotfix
# Or if the directory was already deleted:
git worktree prune

Parallel CI/Testing Pattern

Copy
# Run tests on a branch without switching
git worktree add /tmp/test-run feature/new-api
cd /tmp/test-run
npm install
npm test
cd -
git worktree remove /tmp/test-run

Worktree for Code Review

Copy
# Check out a PR branch for review without disrupting your work
git fetch origin pull/123/head:pr-123
git worktree add ../review-pr-123 pr-123

# Review in the separate directory
cd ../review-pr-123
# ... review, run tests, etc.

# Clean up
cd ../project
git worktree remove ../review-pr-123
git branch -D pr-123

Shared vs. Per-Worktree

Copy
## What's Shared Across Worktrees
- .git directory (refs, objects, config)
- Remote tracking branches
- Git hooks
- Git config

## What's Per-Worktree
- Working directory files
- Staged changes (index)
- node_modules (must npm install separately)
- .env files (not tracked)
- Build output (dist/, .next/, etc.)

Rules

• Always verify git status is clean before creating a worktree
• Never create a worktree for a branch that's already checked out in another worktree
• Always npm install in new worktrees — node_modules is not shared
• Copy .env files to new worktrees if needed (they're not tracked by git)
• Use descriptive directory names: project-hotfix, project-review-pr-123
• Clean up worktrees when done: git worktree remove <path>
• Run git worktree prune periodically to clean up stale entries
• Worktree directories should be siblings of the main repo, not inside it
• Never delete a worktree directory manually — use git worktree remove
• If you must delete manually, run git worktree prune afterward

Examples

User: I need to fix a production bug but I'm in the middle of a feature Action: Create worktree for hotfix branch, fix bug there, push, create PR, return to feature work

User: I want to test two branches side by side Action: Create worktree for each branch, run both apps on different ports

User: How do I review a PR without losing my work? Action: Fetch PR branch, create worktree, review in separate directory, clean up when done