Git Worktrees: Parallel Development Without the Checkout Penalty

The Problem: Stuck in Checkout Hell

When you're juggling multiple feature branches, Git's default behavior forces painful context switches. Need to fix a production bug while a feature sits 200 commits ahead? You stash, switch branches, make changes, then switch back and hope your work isn't conflicted. This isn't development—it's version control ping-pong.

The Solution: Git Worktrees

Git worktrees let you attach multiple working directories to a single repository. Think of them as lightweight, parallel universes sharing the same Git history but with independent working files. You can have main checked out in one directory, a feature branch in another, and even a hotfix branch in a third—all simultaneously.

How They Work

When you run git worktree add, Git creates a new directory with its own working files but shares the .git directory. This means no duplicate object storage—changes to the same files across worktrees are still tracked efficiently.

A Real Example: Feature + Hotfix Workflow

Let's say you're building a payment integration feature but need to patch a critical security issue:

# From your main repository directory
# Check current worktrees
$ git worktree list
/path/to/repo [master]

# Add a worktree for the feature branch
$ git worktree add ../payment-feature feature/payment-integration
 Preparing 'feature/payment-integration' (main)

# Add a worktree for the hotfix
$ git worktree add ../hotfix/security-patch hotfix/security-2024
 Preparing 'hotfix/security-2024' (main)

# Now you have three active worktrees
$ git worktree list
/path/to/repo               (bare)
/path/to/repo/../payment-feature   feature/payment-integration
/path/to/repo/../hotfix/security-patch   hotfix/security-2024

In one terminal, you're working on the feature. In another, you're fixing the security issue. Both branches are checked out simultaneously. When done:

# Remove worktrees when finished
$ git worktree remove ../payment-feature
$ git worktree remove ../hotfix/security-2024

Important Caveats

Don't run Git operations from non-principal worktrees. Commands like git gc, git repack, or branch deletions should only run from your main repository directory to avoid corrupting shared Git metadata.

Worktrees can't be nested. If you try git worktree add ./subdir branch inside an existing worktree, Git will refuse. This prevents confusing directory hierarchies.

The principal worktree is protected. Your main repository directory cannot be removed with git worktree remove. This ensures you always have a valid working directory.

When Worktrees Don't Fit

• Large file changes: If you're switching between branches with completely different large files, the shared object database still gets populated, though the working files themselves are separate.
• CI/CD isolation: For completely isolated builds, separate clones might be cleaner despite the disk overhead.
• Windows file locking: Some operations can fail if files are locked by other processes.

Actionable Next Steps

Start small: try creating a worktree for your next feature branch instead of switching in your main directory. Run git worktree list to see what you have active. When you're comfortable, integrate worktrees into your daily workflow for any parallel branch work.

Pro tip: Add an alias like git wl for git worktree list to quickly check your active worktrees.