Git Worktree Workflow for Juggling Two Branches at Once
You are halfway through a feature branch with twelve modified files when someone asks you to check a production bug right now.

You are halfway through a feature branch with twelve modified files when someone asks you to check a production bug right now. Stashing, switching, rebuilding and then remembering what you were doing costs twenty minutes and a fair amount of nerve. A git worktree workflow removes that whole dance: you keep your feature branch open in one folder and check out the hotfix in another, both backed by the same repository.
Git has shipped worktrees since version 2.5 in 2015, yet most developers I talk to have never typed the command. This guide covers the folder layout that stays tidy, the five commands you actually need, the traps that catch people in the first week, and when a plain stash is still the better tool.
What a git worktree actually is
A normal clone has one working directory attached to one .git folder. A worktree is an extra working directory attached to that same .git folder. Every worktree has its own checked out branch, its own index and its own uncommitted changes, but they all share one object database, one set of remotes and one reflog.
That sharing is the point. A second full clone of a 2 GB monorepo costs another 2 GB and another long fetch. A second worktree costs only the size of the checked out files, and it appears in a couple of seconds because nothing is downloaded. Commit in one worktree and the commit is instantly visible from the other, with no push or pull in between.
A folder layout that stays readable
The most common mess is creating worktrees inside the main repository folder, where your editor, your test runner and your file watcher all start indexing them twice. Put them next to the repository instead. A layout that has held up for me on several client projects looks like this:
- ~/code/shop is the main checkout, usually on the main branch or your long running feature
- ~/code/shop-hotfix is a worktree reserved for urgent fixes
- ~/code/shop-review is a worktree you reuse for reading other people's pull requests
Two or three long lived worktrees beat a new folder per branch. Reusing shop-review for every review means your dependencies are already installed there, and switching it to the next pull request is one checkout instead of a fresh setup.
The five git worktree commands you need
Run these from anywhere inside the main repository. Paths are relative to where you are standing.
- Create a worktree on a new branch: git worktree add ../shop-hotfix -b hotfix/login-timeout origin/main. This creates the folder, creates the branch from the remote main, and checks it out.
- Create a worktree on an existing branch: git worktree add ../shop-review feature/new-cart. Use this for reviews after a git fetch.
- See what you have: git worktree list prints every worktree, its path, the commit it sits on and the branch name.
- Remove one cleanly: git worktree remove ../shop-hotfix. Git refuses if there are uncommitted changes, which has saved me from deleting real work more than once. Add -f only when you are sure.
- Clean up stale entries: git worktree prune drops records for folders you deleted by hand.
The traps that catch people in week one
One branch, one worktree
Git will not let the same branch be checked out in two worktrees at once. If you try, you get an error saying the branch is already used by another worktree. This is a safety rule, not a bug. Two working directories moving the same branch pointer would corrupt each other's view of history. If you need to look at the same code twice, check out the commit in detached mode or create a throwaway branch.
Untracked files do not follow you
A new worktree contains only tracked files. Your .env file, your node_modules folder, your Python virtual environment and any local certificates stay behind in the main checkout. Plan for this. If you already manage variables with per project environment variables through direnv, copy the .envrc into the new folder and run direnv allow once. For JavaScript projects, a fresh npm ci in a worktree on a mid sized app takes around 40 to 90 seconds, which is still faster than stashing and rebuilding.
Hooks are shared
Hooks live in the common .git directory, so every worktree runs the same ones. That is usually what you want. If your team relies on pre-commit hooks that small teams actually keep using, they will fire in the hotfix worktree too, which is exactly the place where a rushed commit needs a linter most.
Ports and containers collide
Two worktrees running the same dev server will fight over port 3000. Docker Compose names a project after its folder by default, so shop and shop-hotfix get separate containers and volumes, which is good, but both will still try to publish the same host ports. Set the port through an environment variable in each worktree. The same idea is covered in more depth in our guide to Docker Compose for local development.
Where common advice overshoots
Once people discover worktrees, a popular suggestion follows: stop using git stash entirely and give every branch its own folder. I disagree, for a practical reason.
A worktree has a setup cost. Dependencies, environment files, build caches and editor windows all multiply. For a switch that lasts under five minutes, such as checking how a function looked on main or grabbing a line from another branch, git stash or even git show main:path/to/file is faster and leaves nothing behind. Ten worktrees with ten copies of node_modules can easily eat 8 GB of disk on a laptop that was already tight.
My rule is simple. If the interruption needs a build, a test run or more than about fifteen minutes, use a worktree. If it is a quick look, stash or show. And keep the total under four worktrees, because past that point you start losing track of which folder holds which half finished idea.
A real interruption, start to finish
Here is the sequence I use when a bug report lands mid feature, with typical timings on a mid sized web app:
- git fetch origin, about 3 seconds.
- git worktree add ../shop-hotfix -b hotfix/cart-total origin/main, about 2 seconds.
- Open the new folder in a second editor window, copy the environment file, install dependencies, under 2 minutes.
- Fix, test and commit inside shop-hotfix, then push and open the pull request.
- Close that editor window and return to the untouched feature branch, exactly where you left it, with the test watcher still running.
- After the merge, git worktree remove ../shop-hotfix and git branch -d hotfix/cart-total.
Nothing in your feature folder moved. No stash to pop, no forgotten untracked file, no rebuild of a cache that took ten minutes to warm.
Frequently asked questions
Is git worktree better than cloning the repository twice?
For most cases, yes. A worktree shares the object database, so it uses far less disk and needs no extra fetch. Commits made in one worktree are visible in the other immediately, while two clones need a push and pull to see each other's work.
Can I delete a worktree folder with rm?
You can, and nothing breaks, but Git keeps a stale record until you run git worktree prune. Using git worktree remove is safer because it refuses to delete a folder with uncommitted changes. That single check is worth the extra few keystrokes.
Do IDEs support git worktrees?
VS Code and the JetBrains IDEs treat a worktree as a normal folder and show its branch correctly. Open each worktree in its own window rather than adding it to the main workspace, or search and indexing will run twice over nearly identical files.
More in Dev Tools
Dev Tools
Git includeIf Setup for Work and Personal Identities
The commit that made me fix this properly had my personal address on it, sitting in a client repository, pushed to a branch...
Dev Tools
Sign Git Commits With an SSH Key in Fifteen Minutes
Anyone can set their Git name and email to yours. It takes one line of config, no password and no access to your accounts, and...
Dev Tools
Git Bisect to Find the Commit That Broke Your Build
The build passed on Monday and fails on Thursday, and there are 140 commits in between.