Git Worktree Explained

What and Why

Sometimes you need to check out another branch without losing your current work. The usual options are stashing, committing WIP, or cloning the repo a second time. git worktree gives you a cleaner answer: a separate working directory tied to the same .git data, so you can have multiple branches checked out at the same time.

Mental Model

A repo’s .git directory holds all the objects. A working tree is just a checkout of one branch. Worktrees let one .git back many directories. Branches are still mutually exclusive across worktrees; you cannot check out the same branch in two places.

my-repo/.git    (objects, refs)
 |
 +-- working tree A (main)
 |
 +-- worktree B (feature/login) at ../my-repo-login
 |
 +-- worktree C (hotfix/v2) at ../my-repo-hotfix

Hands-on Example

You are mid-feature, then a production bug needs a hotfix.

cd ~/code/my-repo
git status                       # dirty working tree on feature/x

# Create a new worktree from main for the hotfix
git worktree add ../my-repo-hotfix -b hotfix/payments main

cd ../my-repo-hotfix
# edit, test, commit
git push -u origin hotfix/payments

Your feature branch in the original directory was never touched. When you are done with the hotfix, remove the worktree.

cd ~/code/my-repo
git worktree remove ../my-repo-hotfix

List current worktrees.

git worktree list
# /Users/sam/code/my-repo         abc1234 [feature/x]
# /Users/sam/code/my-repo-hotfix  def5678 [hotfix/payments]

Combine with bisect to keep your main checkout intact.

git worktree add ../my-repo-bisect HEAD
cd ../my-repo-bisect
git bisect start HEAD v1.0
git bisect run ./check.sh
git bisect reset
cd -
git worktree remove ../my-repo-bisect

Worktrees also make great CI runners. A single clone with multiple worktrees uses far less disk than cloning per job.

git fetch --all --prune
git worktree add ../ci-run-12 origin/pr/12
# run pipeline in ../ci-run-12
git worktree remove ../ci-run-12

Common Pitfalls

• Trying to check out the same branch twice. Git will refuse. Use git switch -d <ref> for a detached HEAD if you just need to inspect.
• Forgetting to remove worktrees after use. Stale worktrees pile up and confuse git status from the main repo.
• Editing the same file in two worktrees and getting confused. Treat each worktree as a separate concern.
• Deleting a worktree directory manually without git worktree remove. The metadata lingers; clean it with git worktree prune.

Practical Tips

• Add a script wrapper that names worktrees consistently, e.g. worktree add wt-<branch>.
• Keep worktrees as siblings to the main repo for short paths.
• Use git config --worktree for per-worktree settings, like a different remote for review.
• Combine with direnv or .envrc to load environment vars automatically when you cd into a worktree.
• When disk is tight, use git worktree add --detach for read-only inspection without checking out a branch.

Wrap-up

git worktree removes the friction of switching contexts. You stop stashing, you stop cloning, and you keep your tools and editor pointed at the right place for each task. Add a worktree for the hotfix, another for the review you are about to do, and one more for the bisect session, then delete them when you are done. It is a small command with an outsized impact on day-to-day productivity.