Git Worktree Workflows - Comprehensive Guide

This guide teaches you how to master Git worktrees using the gw CLI tool for optimized development workflows.

Table of Contents

1. Git Worktree Fundamentals
2. Creating and Managing Worktrees with gw
3. Navigating Between Worktrees
4. Listing and Inspecting Worktrees
5. Common Workflow Patterns
6. Cleanup and Maintenance
7. Troubleshooting Common Issues

---

1. Git Worktree Fundamentals

What are Git Worktrees?

Git worktrees allow you to have multiple working directories attached to a single repository. Instead of switching branches in your current directory, you can check out different branches in separate directories simultaneously.

Traditional branch switching:

# Your current work is interrupted
git checkout feature-a     # Work on feature A
git checkout feature-b     # Switch context, lose focus
git checkout main          # Switch again for hotfix

With worktrees:

# Each branch has its own directory
/repo.git/main/           # Main branch always ready
/repo.git/feature-a/      # Feature A development
/repo.git/feature-b/      # Feature B development in parallel
/repo.git/hotfix-123/     # Hotfix without interrupting features

Worktree vs Branch Switching vs Cloning

When Worktrees Shine

Worktrees are ideal for:

• Parallel feature development - Work on multiple features without context switching
• Hotfix workflows - Handle urgent bugs while continuing feature work
• Code reviews - Check out PR branches without disrupting your current work
• Testing - Test multiple versions or configurations simultaneously
• Long-running experiments - Keep experimental branches separate from main work
• Build artifacts - Separate build processes without conflicts

Worktree Limitations and Gotchas

What worktrees share:

• ✅ Git repository (.git directory)
• ✅ Commit history and objects
• ✅ Branches and tags
• ✅ Stashes
• ✅ Hooks and config

What worktrees DON'T share:

• ❌ Working directory files
• ❌ Untracked files
• ❌ node_modules (unless symlinked)
• ❌ Build artifacts
• ❌ .env files (unless copied)

Important limitations:

• You cannot check out the same branch in multiple worktrees simultaneously
• Each worktree needs its own dependencies installed (node_modules, vendor/, etc.)
• IDE workspace settings may need adjustment for each worktree
• Some Git UI tools have limited worktree support

---

2. Creating and Managing Worktrees with gw

The gw add Command

The gw add command is an enhanced version of git worktree add with automatic file copying:

# Basic usage - create worktree for existing branch
gw add feature-auth

# Create worktree with new branch
gw add feature-payments -b feature-payments

# Create from specific start point
gw add hotfix-security -b hotfix-security main

# Force creation (even if branch already checked out elsewhere)
gw add feature-test --force

Auto-Copying Files

When creating worktrees with gw add, files configured in .gw/config.json are automatically copied:

{
  "root": "/Users/you/projects/myapp.git",
  "defaultBranch": "main",
  "autoCopyFiles": [
    ".env",
    ".env.local",
    "secrets/",
    "components/ui/.vercel/"
  ]
}

What gets copied:

• Environment files (.env, .env.local)
• Secrets and credentials
• Local configuration
• Cache directories (if needed)

What should NOT be auto-copied:

• node_modules (install fresh or symlink)
• Build artifacts (build fresh)
• Large binary files
• IDE settings (.vscode/, .idea/)

Example creating a worktree with auto-copy:

$ gw add feature-new-dashboard

Creating worktree feature-new-dashboard...
✓ Branch 'feature-new-dashboard' set up to track 'origin/main'
✓ Worktree created: /projects/myapp.git/feature-new-dashboard

Copying files from main...
✓ Copied: .env
✓ Copied: .env.local
✓ Copied: secrets/api-keys.json
✓ Copied: components/ui/.vercel/

Done! Navigate with: gw cd feature-new-dashboard

Manual File Copying with gw sync

If you need to copy files later or from a different source:

# Copy all autoCopyFiles from config (if configured)
gw sync feature-auth

# Copy specific files from main to current worktree
gw sync feature-auth .env components/agents/.env

# Copy from a different worktree
gw sync --from st

...