git-worktree
Git Worktree
Core Concepts
A git worktree is an additional working directory linked to the same repository. Every repo starts with one worktree (the main worktree). You can add linked worktrees that share the same .git object store, refs, and config.
Shared across all worktrees: object database, refs (branches, tags), config, hooks, remote tracking info, rerere cache.
Isolated per worktree: working tree files, index (staging area), HEAD, MERGE_HEAD, REBASE_HEAD, CHERRY_PICK_HEAD, .env files, node_modules, build artifacts.
The main worktree is the one created by git init or git clone. Linked worktrees are created with git worktree add. The main worktree cannot be removed with git worktree remove -- it is permanent. Linked worktrees can be added and removed freely.
Internally, each linked worktree gets a directory under .git/worktrees/<name>/ containing its own HEAD, index, and tracking files. The linked worktree's working directory contains a .git file (not a directory) pointing back to this location.