Worktree

One-liner

Git worktree creates additional working directories linked to the same repository, letting you work on multiple branches simultaneously.

Why it matters

Context-switching between branches is expensive: stashing work, checking out another branch, waiting for builds, then restoring your state. With worktrees, each branch lives in its own directory. You switch by changing directories, not branches. Your feature work stays exactly as you left it — no stash, no partial commits, no lost state.

Core concept

Imagine your project is a workshop with one workbench. To work on a different task, you'd have to clear the bench, store everything, set up the new materials, work, then reverse the process. A worktree is like having multiple workbenches in the same workshop. Each has its own tools laid out, its own project in progress, but they all share the same storage room (git objects).

Each worktree has its own checked-out branch, its own index, and its own working files — but they share the same .git object database. No duplication of history, no extra clone.

How it works

1. Create — git worktree add <path> <branch> creates a new directory with that branch checked out.
2. Work independently — each worktree is a fully functional working directory; cd between them to switch context.
3. Share objects — all worktrees share the same .git database, so git fetch in one makes objects available to all.
4. Constraint — each branch can only be checked out in one worktree at a time (prevents conflicting modifications).
5. Clean up — git worktree remove <path> deletes the extra directory and its association.

Key terms

• Worktree — an additional working directory linked to the same git repository
• Main worktree — the original clone directory; always exists
• Linked worktree — any additional worktree created with git worktree add
• git worktree list — shows all worktrees with their paths, SHAs, and checked-out branches
• git worktree prune — cleans up references to worktrees whose directories were manually deleted

Common misconceptions

• "Worktrees are just multiple clones" — Clones duplicate the entire object database. Worktrees share it — saving disk space, fetch time, and keeping refs synchronized.
• "You need separate builds for each worktree" — True, and that's a feature. Build artifacts don't contaminate each other; you can have main compiled and running while building a feature branch.
• "Worktrees replace branches" — They complement branches. You still use branches for version control; worktrees give you parallel working directories for those branches.

When to use / not use

✓ Use when: you need to context-switch frequently (hotfixes during feature work), review PRs without disrupting your state, run comparisons between branches, or keep a reference build of main always available.

✗ Don't use when: you only ever work on one branch at a time, disk space is extremely limited, or your build system doesn't support multiple project roots (rare).

Example

# Create a hotfix worktree from main
git worktree add ../project-hotfix -b hotfix/urgent-fix

# Work on it, then clean up when done
cd ../project-hotfix && git push
cd ../project && git worktree remove ../project-hotfix

Next steps

1. Set up a permanent main worktree that stays built for quick comparisons and reference
2. Create a team convention for worktree directory naming (e.g., project-<purpose>)
3. Combine worktrees with IDE workspace features to maintain separate editor states per branch