Git Worktrees

A Git worktree is an extra folder for the same repository, with its own branch checked out. Instead of switching one folder back and forth between branches, you keep main in one folder and your feature in another, and work on both at once.

The cost of switching branches

A normal clone has one working folder, so it can only have one branch checked out at a time. Say you are halfway through a feature-login branch when a bug turns up on main. With one folder, the routine goes:

1. Commit or stash your half-finished work.
2. git switch main, which rewrites files all over the folder.
3. Fix the bug, commit and push.
4. Switch back to feature-login.
5. Restore your stash and try to remember where you were.

Each switch changes files under your editor, so dev servers restart, builds rerun and caches go stale. If the branches have different dependencies, you may need to reinstall them too. Worst of all, it is easy to lose track of which branch you are on and commit to the wrong one.

What a worktree is

A worktree is a working folder: the files you edit, with one branch checked out. Every repository starts with one, the main worktree, which is the folder you cloned into. git worktree add creates linked worktrees: more folders, each with its own branch, all connected to the same repository.

The key point is what they share. There is still only one .git repository, so every worktree sees the same commits, the same branches, the same remotes and the same history. What each one has to itself is its checked-out branch, its files on disk, and its own staging area.

Here is the layout with three worktrees:

Because the history is shared, a commit made in one worktree is visible from every other one straight away. There is nothing to push or pull between them.

Using worktrees: a worked example

Start in your normal clone, app, which has main checked out. Create a worktree for the feature branch next to it:

git worktree add ../app-feature feature-login

That makes a new folder, app-feature, with feature-login checked out. Your original folder stays on main, untouched.

When the bug comes in, give it its own folder and a new branch in one go with -b:

git worktree add -b hotfix-typo ../app-hotfix main

This creates a branch called hotfix-typo, starting from main, and checks it out in app-hotfix. Now you have three folders and can open each in its own editor window. Run the feature's dev server in one, fix the bug in another, and nothing you do in one disturbs the files in the others.

To see them all:

git worktree list

/code/app          fb6e0a8 [main]
/code/app-feature  fb6e0a8 [feature-login]
/code/app-hotfix   fb6e0a8 [hotfix-typo]

Once the fix is merged, remove its folder:

git worktree remove ../app-hotfix

This deletes the folder and Git's record of it. The hotfix-typo branch and its commits are still in the repository, so delete the branch separately if you no longer need it. Git refuses to remove a worktree that has uncommitted changes, so you can't throw work away by accident.

If you delete a worktree folder by hand instead, Git still remembers it. git worktree list marks it as 'prunable', and git worktree prune tidies up the leftover record.

The one rule: one branch, one worktree

A branch can only be checked out in one worktree at a time. With main checked out in app, trying to check it out anywhere else fails:

git worktree add ../app-copy main
# fatal: 'main' is already used by worktree at '/code/app'

The same happens with git switch inside another worktree. The rule exists because a branch is a pointer to its latest commit. If two folders had the same branch checked out, a commit in one would move the branch under the other, leaving its files out of step with its branch without any warning.

If you need the same code in two places, create a new branch from it, as the hotfix example did with -b.

Worktrees or a second clone?

You could get two folders by cloning the repository twice. The difference is what is shared:

With two clones, it is easy to fix something in one and forget it never reached the other. Worktrees avoid that, at the price of the one-branch rule.

When worktrees help

• Working on two things at once. A fix on main while a feature stays open, exactly as above.
• Testing a branch in its own folder. Check out a teammate's pull request, install it and run its tests without touching your own work.
• Long-running jobs. Let a slow test suite or build run in one worktree while you keep coding in another.
• Parallel AI agents. Coding agents that work at the same time each need their own files. Giving each one a worktree and a branch stops them overwriting each other, a pattern that comes up in multi-agent orchestration.

Worktrees don't change how branches work, so they fit whatever branching strategy your team already uses.

Common mistakes

• Expecting to open the same branch twice. Git refuses by design. Create a new branch instead.
• Forgetting about old worktrees. Each one holds a full set of files and keeps its branch 'in use'. Check git worktree list now and then and remove what you are done with.
• Forgetting each folder needs its own setup. Untracked files such as node_modules or a .env file don't appear in a new worktree. Install dependencies and copy local config into it.
• Putting a worktree inside the main folder. Git will then see it as a stray untracked folder. Keep worktrees side by side, such as ../app-feature.

Key takeaways

• A worktree gives you another folder from the same repository, with its own branch checked out.
• All worktrees share one history, so commits are visible everywhere at once.
• The same branch can only be checked out in one worktree at a time.
• Create them with git worktree add, see them with git worktree list, and clean up with git worktree remove.
• Use them to work on two things at once, test a branch in its own folder and keep work separate.