Multiple working trees
git worktree add checks out a second working tree from one repository, sharing a single .git object store. Run a long build or review a PR on branch B while you keep editing branch A — no stash, no second clone. A branch cannot be checked out in two worktrees at once.
You are deep in a feature branch when a colleague asks you to review their PR, which needs a full build to test. Switching branches means stashing your half-done work, waiting on a checkout, building, then unwinding all of it to get back. What if you could just have a second checkout of the same repo open in another folder — on a different branch — at the same time? That is exactly git worktree.
By the end of this lesson you will be able to spin up a second working tree on a different branch, understand why it is cheaper than a second clone, and respect the one rule that keeps worktrees consistent.
After this lesson you can use git worktree add to check out a second working tree from the same repository, list and remove worktrees, explain how they share one object store, and state the rule that a branch cannot be checked out in two worktrees simultaneously.
git worktree add <path> <branch> creates a second working directory tied to the same repository. From inside your repo, you point it at a new folder and a branch to check out there:
git worktree add ../review-pr feature/their-pr
# Preparing worktree (checking out 'feature/their-pr')
cd ../review-pr # a full second checkout, on a different branchNow ../review-pr holds the files for feature/their-pr while your original folder still holds your own branch, untouched. You can build, test, or read in one while editing in the other — no stashing, no branch dance.
All worktrees share one .git object store, which is what makes them cheap. A second git clone copies the entire object database — every commit, tree, and blob — again. A worktree does not: the commits, branches, and history live once in the main repository, and each extra working tree just gets its own checked-out files plus a small administrative pointer:
git worktree list
# /home/you/project a1b2c3d [feature/search]
# /home/you/review-pr 9f3c1a2 [feature/their-pr]Because the object store is shared, a commit you make in one worktree is immediately visible to all the others — they are different windows onto one repository, not separate copies.
A branch can be checked out in only one worktree at a time. Since all worktrees share branches, letting two of them sit on the same branch would mean two working trees fighting over one branch pointer. Git forbids it:
git worktree add ../hotfix main
# fatal: 'main' is already checked out at '/home/you/project'If you genuinely need to base new work on main, create a branch from it for the new worktree instead — git worktree add -b hotfix/login ../hotfix main makes a fresh hotfix/login branch starting at main and checks it out there.
Clean up worktrees with remove, not rm -rf. When you are done, removing the worktree properly also clears git’s internal bookkeeping:
git worktree remove ../review-pr # delete the worktree and its admin entry
git worktree prune # tidy up records of trees deleted by handIf you delete a worktree’s folder manually, git still thinks it exists until you prune. Note also that build artifacts and untracked files in a worktree are local to that folder, so a long-running build in ../review-pr never touches your feature folder.
▸Why this works
Why prefer a worktree over a second clone? Three reasons. Disk and time: no re-downloading or re-copying the whole object database — large repos clone slowly, but a worktree is near-instant. Shared state: commits, fetched refs, and stashes are visible across worktrees because there is one repository, so you do not have to push-and-pull between two clones to move work. One source of truth: a single .git means no risk of two clones silently drifting out of sync. The tradeoff is that they are coupled — corrupt the shared object store and every worktree is affected.
Reviewing a PR without dropping your own work.
You are mid-feature on feature/search with uncommitted edits, and a teammate needs their feature/checkout-redesign reviewed with a real build.
# from your project folder, still on feature/search with dirty files:
git worktree add ../review feature/checkout-redesign
cd ../review
npm install && npm run build # build and test their branch here
# ... leave review comments ...
cd ../project # your dirty feature/search is exactly as you left it
git worktree remove ../review # done — clean upYour feature/search edits never moved: no stash, no commit, no checkout churn. The review build ran in a separate folder against the same shared history, and git worktree remove cleaned it up when you finished. Had you tried git worktree add ../review feature/search, git would have refused — that branch is already checked out in project/.
▸Common mistake
The recurring trap is trying to check out a branch that is already live in another worktree and being confused by fatal: '<branch>' is already checked out. It is not a bug — it is git protecting you from two trees mutating one branch. Either work on a different branch in the new worktree, or create a new branch from the one you wanted (-b). The second trap is deleting worktree folders with rm -rf and leaving stale entries behind; always use git worktree remove, or run git worktree prune to clean up afterward.
git worktree add <path> <branch> gives you a second working tree from the same repository, so you can build, test, or review on one branch while you keep editing another — no stash, no second clone. All worktrees share one .git object store, which makes them cheap and keeps commits instantly visible across them; the cost is that they are coupled. The firm rule: a branch can be checked out in only one worktree at a time — make a new branch (-b) when you need work based on an already-checked-out branch. Clean up with git worktree remove (and prune for hand-deleted folders). Next you will make git itself faster to drive with aliases and config.
Practice
Start at the top. Tasks go easiest → hardest: recall a fact, apply it to a case, then a senior-level stretch. Open one, attempt it, then reveal.
Something unclear?
Ask a question about this lesson. Questions are anonymous and go straight to the author to make the lesson better.