Using Git Worktrees Engine

A practical skill for using Git worktrees to work on multiple branches simultaneously. Covers worktree creation, management, workflows for parallel development, code reviews, and hotfix scenarios without context switching.

When to Use This Skill

Choose this skill when:

• Working on multiple features or branches simultaneously
• Reviewing pull requests while your feature branch has uncommitted work
• Applying hotfixes to production without stashing or losing context
• Running long-running tests on one branch while coding on another
• Comparing implementations across branches side by side

Consider alternatives when:

• Need basic Git branching → use standard Git commands
• Working on a single feature → regular checkout is sufficient
• Need full repository isolation → clone the repository separately
• Managing many microservices → use separate clones per service

Quick Start

Copy
# Create a worktree for a feature branch
git worktree add ../my-project-feature feature/user-auth
cd ../my-project-feature
# Work on the feature without affecting your main worktree

# Create a worktree for a hotfix
git worktree add ../my-project-hotfix -b hotfix/critical-fix main
cd ../my-project-hotfix
# Fix the issue, commit, push, create PR

# Create a worktree for reviewing a PR
git worktree add ../my-project-review pr-123
cd ../my-project-review
# Review code, run tests, without disrupting your work

# List all worktrees
git worktree list

# Remove a worktree when done
git worktree remove ../my-project-feature

Core Concepts

Worktree Workflows

Scenario	Command	Benefit
Parallel features	git worktree add ../feat-B feature-B	Work on two features at once
PR review	git worktree add ../review origin/pr-branch	Review without stashing
Hotfix	git worktree add ../hotfix -b fix main	Immediate fix from clean main
Long tests	git worktree add ../test-run current-branch	Run tests while coding
Comparison	git worktree add ../compare other-branch	Side-by-side code comparison
CI debugging	git worktree add ../ci-debug ci-branch	Reproduce CI failures locally

Worktree Directory Organization

~/projects/
├── my-project/              # Main worktree (usually main/develop)
├── my-project-feature-auth/ # Feature worktree
├── my-project-hotfix/       # Hotfix worktree
└── my-project-review/       # PR review worktree

# Convention: {project}-{purpose} naming
# All share the same .git directory → same remotes, same history
# Each has its own working directory → independent file states

Common Worktree Operations

Copy
# Create worktree from existing remote branch
git worktree add ../review-dir origin/feature-branch

# Create worktree with new branch from specific commit
git worktree add ../hotfix-dir -b hotfix/issue-123 v2.1.0

# Move a worktree to a different directory
git worktree move ../old-location ../new-location

# Prune stale worktree references (after directory deleted manually)
git worktree prune

# Lock a worktree to prevent accidental removal
git worktree lock ../important-worktree

# Run command in a specific worktree
git -C ../other-worktree status

Configuration

Parameter	Type	Default	Description
worktreeBase	string	'../'	Base directory for new worktrees
namingConvention	string	'{project}-{branch}'	Worktree directory naming
autoCleanup	boolean	false	Remove worktree after branch is merged
lockOnCreate	boolean	false	Lock worktrees to prevent accidental removal
shareNodeModules	boolean	false	Symlink node_modules across worktrees
maxWorktrees	number	5	Maximum concurrent worktrees

Best Practices

1. Use a consistent naming convention for worktree directories — Name worktrees by purpose: project-feature-auth, project-hotfix, project-review-123. This makes it obvious what each directory is for when switching between them.

2. Remove worktrees promptly after merging branches — Stale worktrees consume disk space and create confusion. After a PR is merged, git worktree remove the directory. Use git worktree list periodically to audit active worktrees.

3. Run npm install or equivalent in each new worktree — Worktrees share Git history but not node_modules or build artifacts. Each worktree needs its own dependency installation. Consider symlinking shared dependencies for large projects.

4. Never checkout the same branch in two worktrees — Git prevents this by default because it would cause conflicts when committing from either location. If you need the same code in two places, create a new branch from the target branch.

5. Use worktrees for code review instead of stash — When asked to review a PR while working on a feature, create a worktree for the review branch. This avoids the risk of forgetting to stash pop or losing stashed changes.

Common Issues

"fatal: branch already checked out" error — A branch can only be checked out in one worktree at a time. If you need the same code elsewhere, create a new branch: git worktree add ../dir -b review-copy origin/branch.

Node_modules missing in new worktree — Each worktree has its own working directory without shared node_modules. Run npm install in each new worktree. For faster setup, use npm ci which installs from lockfile.

IDE opens wrong worktree or shows stale files — Configure your IDE to treat each worktree as a separate project. In VS Code, open the worktree directory directly (code ../my-project-feature). Don't navigate between worktrees within the same IDE window.