Fix an urgent bug mid-feature with git worktree
Short answer: When an urgent fix lands in the middle of feature work, you don't have to stash, switch branches and rebuild. git worktree add ../hotfix main gives you a second working folder from the same repository with main checked out, so you can fix, test and push there while your half-finished feature stays untouched in the original folder. When you're done, git worktree remove ../hotfix cleans it up. It uses the same repository data, so there's no second clone to keep in sync.
The familiar interruption
You're halfway through a feature with a dozen changed files, a local database migration and a dev server running. A message arrives: the checkout page is broken in production and needs fixing now. The usual dance:
- Stash or make a messy "WIP" commit.
- Switch to
main, pull, install dependencies that differ between branches. - Fix, test and push.
- Switch back, unstash, reinstall, hope the stash applies cleanly and that you remember where you were.
It works, but it's slow and error-prone, and it's how half-finished changes end up in hotfixes or stashes get forgotten.
What a worktree is
Git's documentation explains that a repository can support multiple working trees, letting you check out more than one branch at a time. Each additional one is called a "linked worktree", as opposed to the main worktree created by git init or git clone. All worktrees share the same repository data: commits, branches and remotes. Only the files on disk and each folder's checked-out branch are separate.
In practice, that means two or more folders on your machine, each on its own branch, all part of the same repository. A commit made in one is immediately visible to the others.
Handling an urgent fix with a worktree
- From your feature folder, create a worktree for the fix:
git worktree add -b hotfix/checkout ../shop-hotfix origin/mainThis creates a new branchhotfix/checkoutfrom the latestmainand checks it out in a sibling folder../shop-hotfix. Rungit fetchfirst soorigin/mainis current. - Open the new folder in your editor or a second terminal. Install dependencies if the project needs them.
- Fix, test and commit as normal in that folder.
- Push and open a pull request, or follow your usual hotfix process.
- Go back to your feature folder. Everything is exactly as you left it: uncommitted changes, running server and all.
- Remove the worktree when the fix is merged:
git worktree remove ../shop-hotfix
Rules worth knowing
One branch, one worktree. Git won't let you check out the same branch in two worktrees at once, which protects you from editing a branch from two places. If you need main in a second folder while it's checked out elsewhere, create a new branch from it, as in the example, or use --detach for a read-only look.
Clean up properly. Deleting the folder by hand leaves Git with a record of a worktree that no longer exists. git worktree remove is the tidy way; if you've already deleted the folder, git worktree prune clears the stale record. git worktree list shows what you have.
Locks for removable drives. If a worktree lives on an external drive or a network share that isn't always connected, git worktree lock stops Git pruning it while it's away.
Moving folders. Use git worktree move rather than moving the folder yourself, or run git worktree repair afterwards so Git can find it again.
Other good uses
- Reviewing a colleague's pull request without disturbing your own work: check out their branch in a worktree, run it, read the code, remove it.
- Comparing behaviour between
mainand your branch side by side, each running on a different port. - Long-running jobs, such as a slow test suite or build on one branch, while you keep coding on another.
- Release branches you maintain alongside current development, each with its own folder.
Practical tips
- Keep worktrees next to the main folder with clear names (
shop,shop-hotfix,shop-review), so you always know where you are. - Remember per-folder setup. Each worktree has its own
node_modules, build output and local environment file. Copy the environment file if your app needs one, and don't commit it. - Watch shared resources. Two dev servers can't use the same port, and two copies of the app may share a local database. Use separate ports and, if needed, separate databases.
- Show the branch in your prompt. Most shells and editors can display the current branch, which helps when several folders look alike.
When not to bother
Worktrees shine when switching is expensive: big dependency installs, long builds, local services or uncommitted work you don't want to disturb. For a tiny repository where switching takes seconds and you have nothing uncommitted, a plain git switch is fine. Some teams also find that worktrees confuse tools that expect one folder per repository, such as certain editor plugins or scripts with hard-coded paths. Try it on one interruption before making it the team's standard routine.
A worked example
Picture a hypothetical Edinburgh ticketing start-up developer midway through a seat-selection feature with a migration applied locally. A bug in production was sending duplicate confirmation emails. She created a worktree from the latest main on a new hotfix branch, installed dependencies there, fixed the email trigger, ran the relevant tests and pushed for review. Twenty minutes later she was back in her feature folder with nothing to unstash. Once the hotfix was merged, she removed the worktree and pruned the branch.
FAQ
Is a worktree the same as cloning the repository twice?
Similar on disk, but worktrees share one set of repository data, so branches and commits are instantly shared and there's no second remote to fetch.
Can I use worktrees with my editor?
Yes. Each worktree is a normal folder; open it as a separate project or window.
Do worktrees take a lot of disk space?
Each one holds a full copy of the checked-out files and any installed dependencies, but not a second copy of history.
What happens to a worktree's branch after I remove it?
The branch stays in the repository. Delete it separately once it's merged.
If interruptions keep derailing your team's Git workflow, tell us how you handle urgent fixes and we'll suggest a smoother routine.