Git Worktrees

Git Worktrees

Work on multiple branches simultaneously without stashing or switching.

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
+-- ...

Benefits

Common Workflows

1. Parallel Feature Development

# 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

# 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

# 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

# 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

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

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

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

# Continue normal work in main repo
cd ../project

4. Hotfix While Mid-Feature

# 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

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.

Troubleshooting

When to Use This Skill

• Working on multiple features simultaneously
• Reviewing pull requests without disrupting work
• Running long-term experiments
• Handling urgent hotfixes mid-feature
• Testing different branches side by side
• Comparing code across branches

Converted and distributed by TomeVault — claim your Tome and manage your conversions.