Git Worktree Explained: Work on Two Branches at Once
Git worktree lets one repository have several working folders, each with a different branch checked out. Fix an urgent bug without stashing your half-finished feature, review a pull request while tests run, or compare two versions side by side. We ran every command (add, list, remove, prune, lock) and recorded the errors you will meet along the way.
- Git worktree adds extra working folders to one repository; all of them share the same commits, branches and remotes.
git worktree add -b hotfix ../app-hotfixcreated a new branch and a folder for it in one step.- A branch can be checked out in only one worktree at a time; trying again failed with “is already used by worktree”.
- Deleting a worktree folder by hand left a stale entry marked “prunable” until we ran
git worktree prune.
You are halfway through a feature, with files changed everywhere, when an urgent production bug arrives. The usual options are all awkward: commit half-finished work, stash it and hope you remember, or clone the whole repository again. Git worktree offers a cleaner way: a second folder, attached to the same repository, with a different branch checked out. Your feature stays exactly as it is while you fix the bug next door.
We ran every command on Git 2.56.0 in a throwaway repository. Paths in the output are shortened to /work for readability.
What is a git worktree?
Every repository already has one worktree: the folder you cloned, called the main worktree. git worktree add creates linked worktrees, extra folders whose .git entry is a small file pointing back at the main repository’s .git directory. They all read and write the same object database, so a commit made in one is instantly visible in the others, without pushing or fetching.
Why not just stash or clone?
| Option | Downside |
|---|---|
git stash |
One working folder only; easy to forget or mix up stashes; build caches and editor state are lost when switching |
| Second clone | Copies the whole history again, has its own branches and remotes, needs fetch and push to share commits |
| Worktree | Shares everything except the checked-out files; each folder keeps its own build output and editor windows |
Switching branches in place also forces your tools to rebuild and re-index everything. With worktrees, each branch keeps its own folder, so a long test run on one branch does not block coding on another. For background on branches, see our git branch guide.
Our test repository
git init -b main app
cd app
echo "v1" > app.txt; git add .; git commit -m "initial"
git switch -c feature
echo "feature work" >> app.txt; git commit -am "feature in progress"
git switch main
We have main at commit 81608f0 and a feature branch one commit ahead, at 4e6f796.
Adding a worktree with a new branch
git worktree add -b hotfix ../app-hotfix
Preparing worktree (new branch 'hotfix')
HEAD is now at 81608f0 initial
-b hotfix created a new branch starting from the current commit, and ../app-hotfix is the folder to create. Putting worktrees next to the repository, not inside it, keeps them out of git status and your editor’s search. If you leave out -b, Git names the new branch after the last part of the path, so git worktree add ../hotfix would create a branch called hotfix.
Checking out an existing branch
git worktree add ../app-feature feature
Preparing worktree (checking out 'feature')
HEAD is now at 4e6f796 feature in progress
Give the branch name as the second argument to open an existing branch in a new folder. This is how you review a colleague’s branch, or run its tests, without touching your own work. You can also start a new branch from any commit or remote branch: git worktree add -b fix-login ../fix origin/main.
Listing worktrees
git worktree list
/work/app 81608f0 [main]
/work/app-feature 4e6f796 [feature]
/work/app-hotfix 81608f0 [hotfix]
Each line shows the folder, the checked-out commit and the branch. The porcelain format, git worktree list --porcelain, prints the same information in a stable machine-readable layout for scripts.
A branch can be checked out in only one worktree
git worktree add ../again feature
fatal: 'feature' is already used by worktree at '/work/app-feature'
git switch feature # from the main worktree
fatal: 'feature' is already used by worktree at '/work/app-feature'
Git refuses to check out the same branch in two places, because a commit in one folder would silently change the files the other one expects. This protects you, but it surprises people: once a branch lives in a worktree, you cannot even switch to it in the main folder. Work on it in its own folder, or remove that worktree first. If you only need to look at a branch, use a detached worktree, shown below.
A complete hotfix workflow
cd ../app-hotfix
echo "fix" > fix.txt; git add fix.txt; git commit -m "hotfix: patch"
cd ../app
git log --oneline --all
4e6f796 feature in progress
82531bd hotfix: patch
81608f0 initial
git merge hotfix # main now contains the fix
ls
app.txt fix.txt
The commit made in app-hotfix appeared in the main folder’s log immediately, with no push or fetch, because both folders share one repository. We merged it into main, and the feature branch was never touched. In a team you would push the hotfix branch and open a pull request instead; the CI pipeline from our GitHub Actions guide runs exactly as it does for any branch.
Removing a worktree
echo dirty >> ../app-feature/app.txt
git worktree remove ../app-feature
fatal: '../app-feature' contains modified or untracked files, use --force to delete it
git worktree remove --force ../app-feature
removed feature
git worktree remove deletes the folder and Git’s record of it, but only if the worktree is clean. With uncommitted changes, it refused, which is a useful safety net. --force removes it anyway and those changes are lost. The branch itself is not deleted: feature still existed afterwards and could be checked out again. You can never remove the main worktree this way.
Deleting the folder by hand, then pruning
rm -rf ../app-hotfix
git worktree list
/work/app 82531bd [main]
/work/app-hotfix 82531bd [hotfix] prunable
git worktree prune -v
Removing worktrees/app-hotfix: gitdir file points to non-existent location
git worktree list
/work/app 82531bd [main]
Deleting the folder with your file manager leaves Git’s metadata behind, and the list marks the entry as prunable. Until it is pruned, the branch still counts as checked out, so you cannot use it in another worktree. git worktree prune cleans up entries whose folders no longer exist; -n shows what it would remove without doing it. Git also prunes old entries automatically during garbage collection, but running it yourself is instant. Prefer git worktree remove so this never happens.
Detached worktrees for looking around
git worktree add --detach ../review HEAD~1
Preparing worktree (detached HEAD 81608f0)
HEAD is now at 81608f0 initial
--detach checks out a commit without any branch, so it never conflicts with the one-branch rule. It is ideal for comparing behaviour with an older release, running a benchmark against the previous commit, or bisecting a bug while you keep coding.
Locking a worktree
git worktree lock --reason "on USB drive" ../review
git worktree list --porcelain
worktree /work/review
detached
locked on USB drive
git worktree remove ../review
fatal: cannot remove a locked working tree, lock reason: on USB drive
use 'remove -f -f' to override or unlock first
git worktree unlock ../review
git worktree remove ../review # removed review
A locked worktree is protected from prune, move and remove. That matters for worktrees on removable drives or network shares, which can look missing while unmounted and would otherwise be pruned. Unlock it before removing, or pass -f twice.
What worktrees share, and what they do not
- Shared: all commits and objects, branches and tags, remotes (see our git remote guide), configuration, and the stash list.
- Per worktree: the checked-out files, the index (staging area),
HEAD, and any in-progress merge, rebase or cherry-pick. - Not handled for you: ignored files such as
node_modules, virtual environments and.envfiles. Each new folder needs its own dependencies installed and its own local settings copied.
In our test the main repository’s .git folder was 87 KB, while each linked worktree held only its own checked-out files, so extra worktrees cost far less disk space than extra clones on large repositories.
Tips and folder layouts
- Use a predictable layout, for example
project/for main andproject-wt/branch-name/for linked worktrees. - Give each worktree its own ports and databases if you run two dev servers at once.
- Clean up regularly with
git worktree listandremove; forgotten worktrees keep branches locked. - Use worktrees with AI coding agents or parallel tasks: each task gets its own folder and branch, and nothing collides.
- Submodules are supported but need extra care; Git refuses to remove a worktree containing submodules without
--force.
Git worktree cheat sheet
| Task | Command |
|---|---|
| New branch in a new folder | git worktree add -b name ../path |
| Existing branch | git worktree add ../path branch |
| Look at a commit | git worktree add --detach ../path commit |
| List | git worktree list |
| Remove | git worktree remove ../path |
| Clean up deleted folders | git worktree prune -v |
| Protect or release | git worktree lock / unlock |
| Move a worktree | git worktree move ../old ../new |
For the rest of everyday Git, see our Git commands cheat sheet.
Final thoughts
Git worktree removes the friction from context switching. Instead of stashing, committing half-done work or cloning again, add a folder for the new task, do the work there, and remove it when you are finished. Remember the three rules we hit in testing: a branch can live in only one worktree, remove worktrees with Git rather than deleting folders, and lock any worktree on a drive that may disappear. With those habits, working on two or three branches at once becomes routine.
Frequently asked questions
What is git worktree used for?
It gives one repository several working folders, each with its own branch checked out, so you can work on a hotfix, a review and a feature at the same time without stashing or cloning.
Can two worktrees use the same branch?
No. Git refuses to check out a branch that is already used by another worktree. Use a detached worktree if you only need to look at the same commit.
How do I delete a git worktree?
Run git worktree remove with the folder path. If you already deleted the folder by hand, run git worktree prune to clean up the leftover entry.
Does removing a worktree delete the branch?
No. The branch and its commits stay in the repository. Delete the branch separately with git branch if you no longer need it.
Is git worktree better than cloning the repository twice?
Usually yes. Worktrees share one history, branches and remotes, so commits are visible everywhere instantly and no history is copied. A second clone is fully independent, which is only useful when you want that isolation.
Keep learning
Need help with testing, WordPress or SEO?
We help teams ship better software and grow their sites. Tell us what you are working on and we will suggest a clear next step.