Git Worktrees: Parallel Branches Without the Context-Switch Tax

The problem: context switching kills flow

You're deep in a feature branch when a production hotfix lands. The usual dance: git stash, checkout main, fix, commit, push, checkout feature, git stash pop — then resolve conflicts. Or you clone the repo again, wasting disk and sync time. Both break momentum.

Git worktrees, built in since Git 2.5 (2015), solve this by letting you check out multiple branches simultaneously into separate working directories, all backed by a single .git repository. Each worktree gets its own HEAD, index, and working tree, while sharing the object database and refs. Disk usage stays low; context switches become a cd away.

How it works under the hood

When you run git worktree add, Git creates a new directory with a full checkout of the target branch. Inside that directory sits a .git file (not a directory) pointing back to the main repository's .git/worktrees/<name> administrative folder. The main repo's .git/worktrees/ holds per-worktree metadata: HEAD, index, and lock files. Because the object database is shared, adding a worktree costs only the working-tree files — typically megabytes, not gigabytes.

Worked example: hotfix alongside feature development

Assume you're on feature/auth-refactor in ~/proj/myapp. A critical bug requires a fix on main.

# From the main worktree (~/proj/myapp)
git worktree add ../myapp-hotfix main
cd ../myapp-hotfix
# Edit, test, commit
# ...
git push origin main
# Return to feature
cd ../myapp
# Continue work; no stash needed

Where to run: any shell with Git ≥ 2.5. Permissions: write access to the parent directory of the new worktree. Expected check: git worktree list shows both paths with their branches. Risk: if the main repo is deleted, all linked worktrees become unusable — keep the primary clone safe.

Common engineering patterns

• Long-running main worktree: keep ~/proj/myapp-main checked out to main for CI/CD builds, quick hotfixes, or reviewing PRs without disturbing feature work.
• Parallel feature worktrees: git worktree add ../feat-payment feature/payment and git worktree add ../feat-notify feature/notify let you run tests in both directories simultaneously.
• Bare repository + worktrees: on servers, use a bare repo as the source: git worktree add -b hotfix-123 ../hotfix-123 main creates the branch and worktree in one step.

Trade-offs and limitations

Area	Behavior	Workaround
Submodules	Not auto-initialized in new worktrees	Run git submodule update --init inside each worktree after creation
Hooks	Per-worktree (.git/hooks)	Symlink or copy hook scripts; consider a shared core.hooksPath
Same branch	Cannot be checked out in two worktrees	Git refuses with "already checked out elsewhere"; use a new branch or detach HEAD
IDE support	Older VS Code, some GUIs miss worktrees	Open each worktree as a separate workspace folder; configure git.worktreeConfig if needed
Locking	Prevents auto-prune on network drives	git worktree lock ../path — remember to unlock when done

Verification checklist

1. Confirm Git version: git --version (needs ≥ 2.5).
2. Test locally: git init demo && cd demo && git commit --allow-empty -m init && git worktree add ../wt-main main && ls ../wt-main.
3. Check disk sharing: du -sh .git ../wt-main — second worktree adds minimal space.
4. Verify isolation: edit a file in one worktree, run git status in the other — no cross-contamination.

When to reach for worktrees

Use worktrees when you need true parallel working directories: concurrent builds, hotfixes without stashing, or reviewing multiple branches side-by-side. Avoid them for throwaway experiments (use git switch --detach or a temporary clone) or when tooling can't handle multiple workspaces. The feature is stable, documented in git help worktree, and supported by all modern Git hosts.

Next time a hotfix interrupts your feature, add a worktree instead of stashing. Your future self will thank you for the clean cd.