Multiple Working Trees with git worktree

Reviewed & published by Brayan K

Need to review a PR while your own work sits half-finished? git worktree lets you check out multiple branches into separate directories that all share one .git — no stashing, no second clone. This lesson covers adding, listing, and removing worktrees, when to use them, and the one rule that keeps them safe.

Part of the free Git course at LearnCodingFast — hands-on lessons with worked examples and the output they print, plus practice exercises and a quick quiz.

What You'll Learn

• Check out multiple branches at once with git worktree add
• List every attached tree with git worktree list
• Remove and prune worktrees cleanly
• How worktrees share one .git object store
• When to use a worktree vs stashing or cloning
• Why you can't check out the same branch twice

1️⃣ Adding a Worktree

git worktree add ../path branch checks out branch into a brand-new directory at ../path. Your current directory stays exactly as it is — perfect for reviewing a PR or running a build without disturbing your in-progress work. Both folders share the same underlying .git, so there's no extra clone.

# You're mid-feature and a teammate asks you to review their PR branch.
# Instead of stashing, spin up a SECOND working directory next to this one.

# Check out the PR branch "feature-login" into a sibling folder ../review
git worktree add ../review feature-login

# Your current directory is untouched — your half-done work is still here.
# Move into the new worktree and build/test the PR there:
cd ../review
git status            # On branch feature-login, clean working tree

2️⃣ Listing Worktrees

git worktree list shows every working tree attached to the repository: its path, the commit it's on, and the branch checked out there. The first line is your main worktree (the original clone); any you've added are linked worktrees.

# See every working tree attached to this ONE repository.
git worktree list

# Each line: path, the commit it's on, and the branch checked out there.
# The first entry is the MAIN worktree (your original clone);
# the others are LINKED worktrees you added.

3️⃣ Removing & Pruning

Finished with a worktree? git worktree remove ../path deletes the folder and its bookkeeping in one clean step. If you deleted the folder by hand instead, Git keeps stale records — clear them with git worktree prune.

# Done with the review? Remove the linked worktree cleanly.
git worktree remove ../review

# If you deleted the folder by hand (rm -rf), Git still has stale records.
# Clear them with prune:
git worktree prune

# Confirm it's gone:
git worktree list

4️⃣ The One Rule: No Branch Twice

A branch can be checked out in only one worktree at a time. Two worktrees on the same branch would fight over its tip and corrupt your state, so Git blocks it. If you just need to inspect a branch that's already out, add the worktree with --detach for a detached-HEAD checkout of the same commit.

# ⚠️ KEY RULE: a branch can be checked out in only ONE worktree at a time.
# Two worktrees pointing at the same branch could fight over its tip.

# This works — different branches in different folders:
git worktree add ../hotfix   hotfix-123
git worktree add ../release  release-2.0

# This FAILS — main is already checked out in the main worktree:
git worktree add ../again main
#   fatal: 'main' is already checked out at '/home/you/project'

# Need to inspect a branch that's already out? Use a detached checkout:
git worktree add --detach ../peek main

Your turn. Add a worktree for a branch, list to confirm it, then remove it. Fill in the three blanks.

# 🎯 YOUR TURN — replace each ___ then run it in your terminal.
# Goal: review a PR branch without disturbing your current work.

# 1) Add a linked worktree for branch "bugfix" in a sibling folder ../bugfix
git worktree ___ ../bugfix bugfix     # 👉 the subcommand that creates a worktree

# 2) List all worktrees to confirm both the main and the new one exist
git worktree ___                      # 👉 the subcommand that lists worktrees

# 3) When finished, remove the linked worktree cleanly
git worktree ___ ../bugfix            # 👉 the subcommand that deletes a worktree

# ✅ Expected: the bugfix worktree appears in step 2, then is gone in a
#    final "git worktree list" after step 3 — your main work untouched throughout.

Common Errors (and the fix)

• "already checked out" error: that branch is in another worktree. Pick a different branch, or add with --detach to inspect the same commit.
• Stale entries in git worktree list: you deleted a folder by hand. Run git worktree prune to clear the leftover records.
• Can't remove a worktree: it has uncommitted changes. Commit or discard them first, or use git worktree remove --force if you're sure.
• Lost track of where worktrees live: run git worktree list to see every path and branch at a glance.

Pro Tips

• 💡 Keep worktrees as siblings: a path like ../review next to your repo keeps things tidy.
• 💡 Parallel builds: one worktree per branch lets you build and test two branches at once.
• 💡 Use --detach to peek: inspect an already-checked-out branch without claiming it.
• 💡 Always remove, don't rm: git worktree remove avoids stale records you'd later have to prune.

📋 Quick Reference

Mini-Challenge: Parallel Builds

No commands given this time — just the plan. Build two branches in parallel from one shared repository.

# 🎯 MINI-CHALLENGE: parallel builds with worktrees.
# No commands given — just the plan. Run each step in your terminal.
#
# 1. In your main worktree, note the current branch with "git worktree list"
# 2. Add a linked worktree for another branch in a sibling directory
# 3. Open two terminals — one per worktree — and run a build/test in each
# 4. Confirm both ran against DIFFERENT branches at the SAME time
# 5. Remove the linked worktree with "git worktree remove", then prune
#
# ✅ Expected: two branches built in parallel from one shared .git, then a
#    clean "git worktree list" showing only the main worktree again.

# your commands here

🎉 Lesson Complete!

• ✅ git worktree add ../path branch checks out a branch into its own folder
• ✅ All worktrees share one .git — far cheaper than a second clone
• ✅ git worktree list shows every attached tree; remove/prune clean up
• ✅ Great for reviewing a PR or running parallel builds without stashing
• ✅ A branch can be checked out in only one worktree at a time

Practice quiz

Continue this course

• Previous: Git Hooks & Automation
• Next: Git LFS & Large Files — Track binaries and large assets with pointer files and an LFS server
• Quick reference: Git cheat sheet

Frequently asked questions

What is a git worktree and how is it different from a branch?

A worktree is a working directory attached to your repository with a particular branch (or commit) checked out into it. A branch is just a pointer to a commit; a worktree is an actual folder on disk where files live. With git worktree you can have several folders, each on a different branch, all backed by the same repository. Switching branches normally swaps files in one folder; worktrees give each branch its own folder so you can have them all checked out at once.

How do worktrees relate to the .git directory?

All worktrees of a repository share a single object database and refs in the main .git directory, so history, commits, and tags are common to all of them. What each worktree keeps separate is its own HEAD, index (staging area), and working files. That sharing is exactly why a worktree is far cheaper than a second clone: you reuse the entire stored history instead of downloading and duplicating it.

When should I use a worktree instead of git stash or a fresh clone?

Reach for a worktree when you need to be on two branches at once. Stash is fine for a quick context switch in place, but it forces you to put your work aside and restore it later; a worktree lets your in-progress branch sit untouched in its own folder while you check out, build, and review another branch elsewhere. Versus a second clone, a worktree saves bandwidth and disk because it shares the existing objects rather than copying the whole repository.

Why can't I check out the same branch in two worktrees?

Git refuses because two worktrees on the same branch would both try to advance that branch's tip, and a commit in one would leave the other's index and files inconsistent. To avoid that corruption, a given branch may be checked out in only one worktree at a time. If you only need to look at a branch that's already checked out elsewhere, add the worktree with --detach to get a detached-HEAD checkout of the same commit without claiming the branch.

How do I clean up worktrees I no longer need?

Use git worktree remove <path> to delete the working directory and its administrative records in one clean step. If you already deleted a worktree's folder by hand, Git still holds stale bookkeeping for it; run git worktree prune to clear those entries. You can always run git worktree list to see exactly which worktrees Git still tracks and where they live.

Related lessons

• Branching and Merging