Git Worktrees Skill

Work on multiple branches simultaneously without stashing or switching

Git worktrees allow you to check out multiple branches at the same time in separate directories. Perfect for parallel feature development, PR reviews, and long-running experiments.

Prerequisites

• Git 2.20+: Worktrees work best with modern Git
• Sufficient disk space: Each worktree is a full working copy
• Understanding: Worktrees share .git data, not working files

Quick Reference

Core Commands

Key Concepts

What is a Worktree?

main-repo/                    # Main worktree (default)
├── .git/                     # Shared Git database
├── src/
└── ...

../main-repo-feature-auth/    # Linked worktree
├── .git → main-repo/.git    # Points to main .git
├── src/                      # Independent working files
└── ...

../main-repo-pr-review/       # Another linked worktree
├── .git → main-repo/.git
├── src/
└── ...

Benefits

Common Workflows

1. Parallel Feature Development

Work on multiple features without context switching:

# You're working on feature A
cd ~/repos/my-project
git checkout feature-a
# ... making changes ...

# Urgent: Need to work on feature B
git worktree add ../my-project-feature-b feature-b

# Now work on feature B in the new directory
cd ../my-project-feature-b
# ... make changes, commit ...

# Go back to feature A - your work is still there!
cd ../my-project

2. PR Review in Isolation

Review pull requests without disrupting your work:

# Fetch the PR
git fetch origin pull/123/head:pr-123

# Create worktree for review
git worktree add ../project-pr-123 pr-123

# Review in the isolated worktree
cd ../project-pr-123
npm install && npm test
# ... run the app, check functionality ...

# Back to your work
cd ../project

# Clean up after review
git worktree remove ../project-pr-123
git branch -d pr-123

3. Long-running Experiments

Keep experimental code separate:

# Create experiment worktree
git worktree add -b experiment/new-architecture ../project-experiment

# Work on experiment over days/weeks
cd ../project-experiment
# ... experimental changes ...

# Lock it to prevent accidental deletion
git worktree lock ../project-experiment

# Meanwhile, continue normal work in main repo
cd ../project

4. Hotfix While Mid-Feature

Handle production issues without losing context:

# Mid-feature, need to hotfix
git worktree add ../project-hotfix main

cd ../project-hotfix
git checkout -b hotfix/critical-bug

# Fix, test, push
git add . && git commit -m "fix: critical bug"
git push origin hotfix/critical-bug

# Clean up and return
cd ../project
git worktree remove ../project-hotfix

Naming Convention

Recommended worktree directory naming:

{repo-name}-{purpose}/

Examples:

• my-app-feature-auth/ - Feature work
• my-app-pr-123/ - PR review
• my-app-experiment-v2/ - Experimental work
• my-app-hotfix/ - Hotfix branch

Best Practices

DO

• ✅ Use descriptive directory names
• ✅ Clean up worktrees after use
• ✅ Lock long-running worktrees
• ✅ Run git worktree prune periodically
• ✅ Keep worktrees in sibling directories

DON'T

• ❌ Create worktrees inside the main repo
• ❌ Delete worktree directories manually (use git worktree remove)
• ❌ Forget to install dependencies in each worktree
• ❌ Have too many worktrees (they take disk space)
• ❌ Share node_modules between worktrees

Worktree + IDE Integration

VS Code

Open each worktree as a separate window:

cd ../project-feature-b
code .

Or use Multi-root Workspaces to see all worktrees.

Recommended Extensions

• GitLens: Visualize worktrees
• Git Graph: See branches across worktrees

Troubleshooting

Performance Tips

1. Shallow clones for reviews: Use --depth 1 when fetching PRs
2. Sparse checkout: Only check out needed directories
3. Shared dependencies: Use npm ci --prefer-offline with shared cache
4. SSD storage: Worktrees benefit from fast disk access

Related Documentation

• Worktrees Workflow Guide
• Reference Documentation
• Worktree Manager Agent
• Helper Script