---

name: git-worktree description: Use this skill for isolated branch workflows and parallel development. Activates when working on features that need isolation, switching contexts, or managing multiple branches.

Git Worktree Skill

Manage isolated development branches without stashing or losing context.

Core Principle

Each feature gets its own workspace.

Git worktrees let you have multiple branches checked out simultaneously in different directories—no stashing, no context switching pain.

What is a Worktree?

Copymy-project/                  # main branch (main worktree)
my-project-feature-auth/     # feature/auth branch (linked worktree)
my-project-bugfix-123/       # bugfix/123 branch (linked worktree)

Each worktree:

• Has its own working directory
• Shares the same .git data (efficient)
• Can have different branches checked out
• Allows true parallel development

Worktree Commands

Create a Worktree

Copy# Create worktree for new branch
git worktree add ../project-feature-name -b feature/name

# Create worktree for existing branch
git worktree add ../project-feature-name feature/name

List Worktrees

Copygit worktree list
# Output:
# /path/to/project         abc1234 [main]
# /path/to/project-feature def5678 [feature/auth]

Remove a Worktree

Copy# After merging/done with feature
git worktree remove ../project-feature-name

# Force remove (discards changes)
git worktree remove --force ../project-feature-name

Prune Stale Worktrees

Copy# Clean up worktrees whose directories were deleted
git worktree prune

Workflow: Feature Development

1. Start Feature

Copy# From main project directory
git worktree add ../myproject-auth -b feature/auth

# Navigate to worktree
cd ../myproject-auth

# Verify clean baseline
npm test

2. Develop in Isolation

Copy# Work normally in worktree
# All changes isolated to feature/auth branch
npm run dev
# ... make changes ...
git commit -m "feat: add login form"

3. Stay Updated with Main

Copy# In feature worktree
git fetch origin main
git rebase origin/main
# or
git merge origin/main

4. Complete Feature

Copy# Ensure tests pass
npm test

# Push for PR
git push -u origin feature/auth

# Return to main
cd ../myproject

# After merge, cleanup
git worktree remove ../myproject-auth
git branch -d feature/auth

Workflow: Hotfix While Feature in Progress

Copy# Currently in feature worktree, need urgent fix

# Create hotfix worktree from main
cd ../myproject  # go to main worktree
git worktree add ../myproject-hotfix -b hotfix/critical-bug

# Fix the bug
cd ../myproject-hotfix
# ... make fix ...
git commit -m "fix: critical bug"
git push -u origin hotfix/critical-bug

# Create PR, get it merged

# Cleanup and return to feature
git worktree remove ../myproject-hotfix
cd ../myproject-auth
git fetch origin main
git rebase origin/main  # get hotfix

Best Practices

Naming Convention

Copy<project>-<type>-<name>
myapp-feature-auth
myapp-bugfix-123
myapp-hotfix-critical
myapp-experiment-new-approach

Directory Structure

Copy~/code/
├── myapp/                    # main (always main/master)
├── myapp-feature-auth/       # feature branch
├── myapp-feature-dashboard/  # another feature
└── myapp-hotfix-123/         # hotfix

Test Baseline Before Starting

Copy# In new worktree, always verify:
npm install  # if needed
npm test     # establish baseline
# Only proceed if tests pass

Don't Forget Cleanup

Copy# After merge, always:
git worktree remove ../path-to-worktree
git branch -d branch-name

Common Issues

"fatal: 'branch' is already checked out"

Copy# Can't checkout a branch that's in another worktree
# Solution: use different branch or remove other worktree
git worktree list  # find where it's checked out

Shared node_modules?

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

IDE Confusion

Copy# Open each worktree as separate project/window
# Don't open parent directory containing multiple worktrees

Integration with Development Flow

With /riper

Copy# Research & Innovate in main worktree
# Plan creates worktree for execution
git worktree add ../project-feature -b feature/x
# Execute in isolated worktree
# Review in worktree, merge to main

With /handoff

Copy# Include worktree info in handoff
worktrees:
  - path: ../project-feature-auth
    branch: feature/auth
    status: in_progress
    notes: Working on OAuth integration

With /ledger

Copy# Track worktree-based tasks
active_worktrees:
  - feature/auth: 75% complete
  - hotfix/123: ready for review

Benefits vs Traditional Workflow