Git Worktree — Parallel Work on Git Branches
git-tools:git-worktree).
View source on GitHub →What a git worktree is
git worktree adds a second working directory with its own branch to a repository. The original checkout stays as it is — uncommitted changes included — and a clean directory for another task appears next to it. No stashing, no risk of one task’s uncommitted changes bleeding into another. For everyday git operations see Git
; for the Gitflow branching model see Git Flow
.
When to use it
- Fixing a bug while another feature is still in progress and shouldn’t be disturbed
- Running two branches at once (e.g. two agents or two terminal sessions working the same repo)
- Reviewing someone else’s pull request without switching your own branch
- Isolated, throwaway experiments that shouldn’t touch the main checkout
- A long build or test run on one branch while development continues on another
Basic commands
git worktree list # all worktrees and their branches
git worktree add ../repo-hotfix hotfix/login # check out an existing branch into a new directory
git worktree add -b fix/login ../repo-fix origin/main # new branch from origin/main
git worktree add --detach ../repo-test v1.4.0 # no branch, just to look at a tag
git worktree remove ../repo-fix # delete the worktree (the branch stays)
git worktree prune # clean up records of hand-deleted directories
git worktree lock ../repo-fix # protect from prune (e.g. on a detachable disk)
git worktree move ../repo-fix ../fix-login # move the directory
Walkthrough: a hotfix next to work in progress
# 1. You are in the middle of feature/checkout when a production bug comes in
git fetch origin
git worktree add -b hotfix/cart-total ../shop-hotfix origin/main
# 2. Fix it in the new directory — the original checkout is untouched
cd ../shop-hotfix
composer install # a worktree installs its own dependencies
# ... fix, tests ...
git commit -am "fix: cart total rounding"
git push -u origin hotfix/cart-total
# 3. Clean up after the merge
cd ../shop
git worktree remove ../shop-hotfix
git branch -d hotfix/cart-total
Where to put worktrees
Two common conventions:
- Next to the repository (
../repo-<task>) — nothing gets in the way inside the working tree; good for individuals. - Inside the repository (
.worktrees/<task>) — everything in one place; good for agents and scripts. The directory has to be in.gitignore, or it shows up ingit status.
Stick to one convention and name by task or ticket number; a month later ../repo-2 tells you nothing.
Common mistakes
| Mistake | What happens | Fix |
|---|---|---|
Deleting the directory with rm -rf | Git still remembers the worktree and keeps its branch marked as checked out | git worktree prune; next time use git worktree remove |
| Checking out a branch that is open elsewhere | fatal: '<branch>' is already used by worktree at … | git worktree list, work there or create a new branch with -b |
| Expecting installed dependencies | A new worktree has no vendor/, node_modules/ or .env — they are not in git | Run the install in the new directory, copy .env |
| Two worktrees on the same database or port | Migrations and tests overwrite each other’s data, the second server won’t start | A database and port per worktree, or run tests from one only |
| Forgotten worktrees | They take up space and block branch deletion | Check git worktree list regularly, remove right after the merge |
| Submodules | They are empty in a new worktree | git submodule update --init in the new directory |
git worktree remove with changes | Git refuses to delete a worktree with uncommitted work | Commit, or use --force deliberately |
Worktrees and AI agents
Two agents in one checkout overwrite each other’s files and commit each other’s changes. A worktree gives each its own directory and branch, so they run side by side and their results meet only in a pull request. The same rule holds for two terminal sessions of one person.
Source
This procedure also exists as an installable Claude Code skill. The maintained version — including the exact commands and edge cases it handles — lives in the git-tools plugin
of the siva01c/claude-plugins
marketplace repository.
Frequently asked questions
What is a git worktree?
A worktree is an additional working directory of the same repository with its own checked-out branch. All worktrees share one history and one .git, so nothing is cloned again and a commit made in one is immediately visible in the others.
What is the difference between git worktree and git clone?
A clone is a separate repository with its own copy of the history, synchronised with the original through push and pull. A worktree is just another checkout of the same repository: it takes the space of the working files, is created in a moment, and shares branches and commits.
When should I use a worktree instead of git stash?
A stash is enough for a few minutes. Once the other task takes longer, has to run at the same time (a long build, tests, a second agent) or you will come back to the work in progress, a worktree is safer — nothing is shelved and both branches stay open side by side.
How do I delete a worktree?
git worktree remove <path> deletes the directory and its record. If you deleted the directory by hand, git worktree prune cleans up the record. The branch stays; git branch -d <branch> removes it.
Why does git say the branch is already checked out?
A branch can be checked out in only one worktree at a time. git worktree list shows which one. Either work there, or create a new branch with git worktree add -b <new-branch> <path> <start-point>.