Mastering Git Worktree for High-Performance Context Switching

Git worktree like a boss

Git Worktree, introduced in version 2.5, enables developers to maintain multiple working directories attached to a single repository history. This system eliminates the need for heavy disk usage or error-prone stashing when switching between feature branches and urgent bug fixes.

Why This Matters

Traditional context switching via git stash or multiple clones introduces significant friction, including redundant storage costs and fragmented local histories. In a multi-clone setup, fetching in one directory leaves others unaware of updates, whereas worktrees share a single internal database. By utilizing a bare clone linked to multiple worktrees, engineers maintain a single source of truth for hooks and configurations while avoiding the disk-space penalty of duplicate 500MB+ repositories.

Key Insights

• Git version 2.5, released in 2015, introduced the worktree command to support multiple simultaneous working trees from a single repository.
• The Bare Clone method uses a hidden .bare directory and a gitdir pointer to keep project roots organized while maintaining full history access.
• Remote tracking must be manually configured in bare clones using ‘git config remote.origin.fetch’ to map remote branches for active development.
• Shared administrative data ensures that universal hooks and local configurations apply across all folders, preventing configuration drift between workspaces.
• Git worktree prevents checking out the same branch in two different worktrees simultaneously, acting as a safety valve against HEAD conflicts.

Working Examples

Recommended ‘Pro’ setup for initializing a bare-clone based worktree environment.

git clone --bare [email protected]:user/repo.git .bare && echo "gitdir: ./.bare" > .git && git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*" && git fetch --all && git worktree add main

Adding a parallel worktree for an urgent hotfix without disturbing the current branch status.

git worktree add ../hotfix && cd ../hotfix

Practical Applications

• Use case: A developer running a heavy test suite in the ‘main’ worktree while simultaneously applying a critical fix in a ‘hotfix’ worktree.
• Pitfall: Removing a worktree directory via ‘rm -rf’ without executing ‘git worktree prune’, which leaves the worktree registered in Git’s internal state.
• Use case: Side-by-side comparison of refactored code and legacy code by checking out different branches into sibling folders for live debugging.
• Pitfall: Encountering a ‘Blind Clone’ where only the default branch is visible because the bare clone was not configured to fetch all remote refs.

References:

• https://dev.to/metal3d/git-worktree-like-a-boss-2j1b