git worktree lets one repository have several working directories at once — branch A checked out in one folder, branch B in another, sharing the same object database. It is the answer to the interruption that stash handles awkwardly: the one where you do not want to put your work away at all.
The basic move #
$ git worktree add ../aospix-hotfix hotfix/cache
Preparing worktree (checking out 'hotfix/cache')
$ ls ../aospix-hotfix # full project, hotfix branch checked out
$ cd ../aospix-hotfix && ... fix, test, commit, push ...
$ cd ../aospix && git worktree remove ../aospix-hotfixThe main directory stays exactly as you left it — build running, editor state, half-finished work. The hotfix happens in a sibling directory against the same history, and when it is merged, the worktree is removed in one command.
Why not just clone? #
A second clone works but re-downloads objects, re-configures remotes, and doubles disk. A worktree shares .git — branches, refs, and history are common, so a commit in one worktree is instantly visible in the other, and a branch checked out in one worktree cannot be checked out in another (git enforces it — no silent conflicts).
| Need | Tool |
|---|---|
| Park changes for two minutes | stash |
| Parallel long-running tasks | worktree |
| A machine-clone of the repo | clone |
| Build/test two branches simultaneously | worktree |
The working patterns #
Long-running structure — main in one directory, next-release in another:
$ git worktree add ../site-main main
$ git worktree add ../site-next next
$ git worktree list
/home/ana/site-main f3e2d1c [main]
/home/ana/site 9a8b7c [next]Review and emergency — a scratch worktree for reading someone's branch or taking a hotfix:
$ git worktree add ../review pr-142
$ # read, build, test; then:
$ git worktree remove ../reviewHousekeeping: git worktree list shows every checkout; prune cleans entries whose directories were deleted by hand; branches whose worktrees are removed become checkout-able again everywhere.
The details worth knowing #
- Untracked files (node_modules, builds) are not shared — each worktree needs its own install. Symlink or script the setup.
- The same repo's hooks and config apply everywhere; a pre-commit hook runs in each worktree.
- Absolute paths are the norm; keep worktrees as siblings of the main checkout, named for their branch.
The branches worktrees check out are branch basics; the pushes that follow hotfixes are remote territory. The Git series continues.