Git worktree lets you work on two branches at once

You are deep in a messy refactor. Half your files are changed, your editor has ten tabs open, and the build is finally warm. Then a bug lands on main and it needs a fix right now. So you stash everything, switch branches, and watch your whole setup vanish.

What if I told you there is a better way?

It's git worktree, and once you start using it, you'll stop reaching for git stash.

What a worktree actually is

Normally a git repo has one folder you work in. You switch branches inside it with git switch, and only one branch can be out at a time. Move to another branch and your files change under you.

A worktree breaks that limit.

It lets you attach more than one working folder to the same repo. Each folder has its own branch checked out, its own staged changes, its own state. But they all share the same history underneath.

So your refactor can sit in one folder on one branch, and a second folder right next to it can be on a different branch. Both are live at the same time. Neither one disturbs the other.

It is not the same as cloning again

You might think you could just clone the repo a second time. You can, but it is heavier than it needs to be.

When you clone again, git copies the entire history to disk all over again. The two copies know nothing about each other. A commit you make in one is invisible to the other until you push and then pull.

A worktree shares the history instead of copying it. It gives you the second folder without paying for a second full repo.

How to make one

The main command is git worktree add. You give it a path for the new folder.

# Make a folder at ../hotfix on a new branch called hotfix
git worktree add ../hotfix

# Pick the branch name yourself
git worktree add -b feature-x ../feature-x

# Check out an existing branch, like a PR you want to review
git worktree add ../review origin/some-pr-branch

# Make a folder at ../hotfix on a new branch called hotfix
git worktree add ../hotfix

# Pick the branch name yourself
git worktree add -b feature-x ../feature-x

# Check out an existing branch, like a PR you want to review
git worktree add ../review origin/some-pr-branch

If you leave off the branch name, git is helpful and names the branch after the last part of the path. So ../hotfix gives you a branch called hotfix. The new folder is a real, normal working directory. You can open it in your editor, run it, and build it, same as any other.

To see everything you have open:

git worktree list

git worktree list

That prints each folder, the commit it is on, and the branch it has checked out.

Cleaning up when you are done

When you finish, do not just delete the folder by hand. Let git remove it, so it also clears its own records.

git worktree remove ../hotfix

git worktree remove ../hotfix

Git will stop you if that folder still has changes you have not committed, which is a nice safety net. If you really mean it, add --force.

And if you did delete a folder by hand at some point, git can tidy up the leftover bookkeeping for you:

git worktree prune

git worktree prune

The one rule that trips everyone up

Here is the thing to remember. You cannot check out the same branch in two worktrees at once.

git worktree add ../another main
# fatal: 'main' is already checked out at '/path/main'

git worktree add ../another main
# fatal: 'main' is already checked out at '/path/main'

This is on purpose. Two folders both committing to main would walk right over each other. If you want a second folder based on main, make a new branch from it with -b, or check it out detached with --detach. Once you know this rule, most worktree confusion goes away.

Where it really pays off

The classic case is the one from the start. You are mid-refactor and an emergency lands. Here is the whole flow.

# Your refactor is dirty and you do not want to touch it.
git worktree add -b emergency-fix ../temp main
cd ../temp

# fix the bug
git commit -am "emergency fix"
git push

cd - # back to your refactor, exactly as you left it
git worktree remove ../temp

# Your refactor is dirty and you do not want to touch it.
git worktree add -b emergency-fix ../temp main
cd ../temp

# fix the bug
git commit -am "emergency fix"
git push

cd - # back to your refactor, exactly as you left it
git worktree remove ../temp

No stash. No rebuild. Your editor tabs and your half-finished work sit untouched the whole time.

There is a newer reason people reach for worktrees too.

If you run AI coding agents, you can give each one its own worktree. They work in separate folders on separate branches, so they never fight over the same files, while still sharing one history. That alone has made worktrees a lot more popular lately.

When not to bother

Worktrees are not free effort. If a quick git stash covers what you need, use stash. If the repo is tiny and cheap to clone, a second clone is fine. Reach for a worktree when your working state is expensive to rebuild, or when you genuinely need two branches live side by side.

So next time

The next time a bug drags you off your branch, do not stash and lose your place. Open a second worktree, fix the thing next door, and come back to your work exactly as you left it. One command, and your whole setup survives.

If breakdowns like this help. Follow along.