Multi-Worktree Development - Comprehensive Guide

Advanced patterns for developing across multiple Git worktrees simultaneously.

Table of Contents

1. Parallel Development Workflows
2. Dependency Management
3. File Synchronization
4. Database and Service Management
5. Testing Workflows
6. Build Artifact Management
7. Team Collaboration
8. Performance and Optimization

---

1. Parallel Development Workflows

Benefits of Parallel Development

Working on multiple branches simultaneously eliminates:

• Context switching overhead
• IDE reindexing delays
• Stashing/committing incomplete work
• Mental context loss

Setting Up Multiple Worktrees

# Create worktrees for different features
gw add feat/user-auth
gw add feat/payment-gateway
gw add feat/email-notifications

# List all worktrees
gw list

Managing Mental Context

Strategy 1: Dedicated terminals

# Terminal 1: User Auth
gw cd feat/user-auth
npm run dev

# Terminal 2: Payment Gateway
gw cd feat/payment-gateway
npm run dev

Strategy 2: Terminal multiplexer (tmux)

# Create named sessions
tmux new -s auth
gw cd feat/user-auth

tmux new -s payments
gw cd feat/payment-gateway

# Switch between sessions
tmux attach -t auth
tmux attach -t payments

Strategy 3: IDE workspaces

VS Code multi-root workspace:

{
  "folders": [
    {"name": "Auth Feature", "path": "../feat/user-auth"},
    {"name": "Payments", "path": "../feat/payment-gateway"}
  ]
}

Quick Context Switching

# Fast navigation with partial matching
gw cd auth     # Matches feat/user-auth
gw cd pay      # Matches feat/payment-gateway

---

2. Dependency Management

Understanding the Problem

Each worktree has independent working files, including node_modules:

repo.git/
├── main/
│   └── node_modules/     # ~500MB
├── feat/user-auth/
│   └── node_modules/     # ~500MB (duplicate!)
└── feat/payment-gateway/
    └── node_modules/     # ~500MB (duplicate!)

With 5 worktrees: 2.5GB of duplicated dependencies!

Strategy 1: Accept Duplication (Simplest)

Pros: Full isolation, no conflicts Cons: Disk space usage

# Each worktree installs independently
gw add feat/new-feature
gw cd feat/new-feature
npm install

Best for: Testing different dependency versions, small projects.

Strategy 2: Use pnpm (Recommended)

pnpm uses a content-addressable store that deduplicates packages:

# Install pnpm
npm install -g pnpm

# In each worktree
gw cd feat/user-auth
pnpm install  # Uses shared store

gw cd feat/payment-gateway
pnpm install  # Reuses cached packages

Result: Near-zero duplication, full isolation.

Strategy 3: Symlink node_modules (Advanced)

Warning: Only works if all worktrees need identical dependencies.

# In feature worktree
gw cd feat/user-auth
rm -rf node_modules
ln -s ../main/node_modules node_modules

Risks:

• Package version conflicts
• Native modules may break
• Hoisting issues

Best for: Read-only testing, identical environments.

Strategy 4: Post-Add Hook for Auto-Install

gw init --post-add "npm install"

Now every gw add automatically installs dependencies.

---

3. File Synchronization

Using gw sync

Sync files between worktrees without recreating them:

# Sync all autoCopyFiles from config
gw sync feat/user-auth

# Sync specific file from main to feature branch
gw sync feat/user-auth .env

# Sync from specific source
gw sync --from staging feat/user-auth .env

# Sync multiple files
gw sync feat/user-auth .env secrets/ config/local.json

Common Sync Patterns

Pattern 1: Update secrets across all worktrees

# After updating .env in main - sync autoCopyFiles to all worktrees
for worktree in $(gw list | grep -v main | awk '{print $1}' | xargs -n1 basename); do
  gw sync "$worktree"
done

# Or sync specific file
for worktree in $(gw list | grep -v main | awk '{print $1}' | xargs -n1 basename); do
  gw sync "$worktree" .env
done

Pattern 2: Propagate config changes

# Updated shared config in main
gw cd feat/user-auth
gw sync --from main feat/user-auth config/shared.json

Pattern 3: Hot-swap environment

# Test feature with production-like config
gw sync --from production-mirror feat/user-auth .env

Dry Run Mode

Preview what would be synced:

gw sync --dry-run feat/user-auth .env secrets/

---

4. Database and Service Management

Database Isolation Strategies

Strategy 1: Separate databases per worktree

# In feat/user-auth/.env
DATABASE_URL=postgresql://localhost:5432/myapp_auth

# In feat/payment-gateway/.env
DATABASE_URL=postgresql://localhost:5432/my

...