Every software engineer knows the disruption: you are in the middle of a complex, multi-file refactoring on your feature branch with uncommitted test runs and partial edits. Suddenly, an urgent production hotfix arrives, or a team member asks for an immediate code review. The traditional response—git stash followed by git checkout main—frequently leads to merge conflicts, lost context, and painful test cache re-indexing.
What is a Git Worktree?
Introduced in Git 2.5, git worktree allows a single local Git repository to have multiple working directories attached to it simultaneously. Each directory checks out an independent branch while sharing the same underlying .git object store, commit history, and ref logs.
Key Advantages Over Stashing and Re-Cloning
- Zero Disk Duplication: Unlike re-cloning a 5GB repository into a second folder, worktrees share the same Git database. Adding a new worktree takes only a few megabytes.
- Simultaneous Local Servers: You can run a development server on
feature-branchon port 3000 while simultaneously running themainbranch on port 3001 to visually verify differences side by side. - Unbroken Flow State: Your uncommitted scratch files, open terminal tabs, and editor workspace remain completely untouched on your feature directory.
Practical Commands for Everyday Mastery
1. Creating a New Worktree
To inspect or work on a branch in a dedicated directory outside your active tree, run:
git worktree add ../project-hotfix hotfix/login-bug
This creates a new sibling folder named project-hotfix with the hotfix/login-bug branch checked out. You can open a new editor window in that folder, make your commits, push your pull request, and close it when finished.
2. Listing Active Worktrees
To see all active working trees and their associated branches, execute:
git worktree list
3. Cleaning Up Completed Worktrees
Once your hotfix is merged and deployed, remove the directory and prune the Git reference cleanly:
git worktree remove ../project-hotfix
Best Practices for Repository Organization
To keep your filesystem clean, adopt a structured naming convention. Create a root directory named after your project (e.g., ~/work/billing-api/) and place your branches inside subdirectories: main/, hotfix/, feature-auth/. This organizational clarity transforms multi-tasking into an effortless, friction-free routine.