Skip to content
New: answer your agents from your phoneLearn more

Git worktree tutorial: work on two branches at once.

A worktree is a second folder for the same repository, checked out on another branch. Fix a bug, review a pull request or run an agent there without stashing or touching your current work.

What a Git worktree is

A Git repository normally has one working directory, the folder where your files live. To look at another branch you stash or commit what you're doing and switch. A worktree is a second working directory for the same repository, checked out on a different branch. Each folder has its own files, and you can work in either without touching the other.

Worktrees share the repository's history, so they're quick to create and take only the space of the checked-out files. A commit you make in one shows up in the others straight away, with no push or fetch.

When a worktree helps

  • An urgent fix mid-feature. Fix the bug in a new worktree and leave your half-finished work exactly as it is.
  • Reviewing a pull request. Check out the branch in its own folder, run it, and close it when you're done, without stashing anything.
  • Long builds or test runs. Let one branch build while you keep coding on another.
  • Comparing two versions. Run the old and new code side by side.
  • Coding agents. Give each agent its own folder so two of them never edit the same files.

Create a worktree

Put worktrees beside your repository, not inside it, so they don't show up as untracked files. To start a new branch from main in a new folder:

$ git worktree add -b hotfix-login ../myapp-hotfix main

To check out a branch that already exists, such as one from a pull request, fetch first and name it. If the branch exists only on the remote, Git creates a local branch that tracks it:

$ git fetch
$ git worktree add ../myapp-review feature-search

Then open the folder in your editor or cd into it. It's a normal checkout: commit, push and pull as usual.

List, move and remove worktrees

See every worktree, with its folder, commit and branch:

$ git worktree list

Move one to another folder:

$ git worktree move ../myapp-review ../review

Remove one when you're done. Git refuses if it has uncommitted changes, unless you add --force. Removing the worktree keeps the branch, so delete that separately once it's merged:

$ git worktree remove ../myapp-hotfix
$ git branch -d hotfix-login

If you deleted a worktree's folder by hand, tell Git to forget it:

$ git worktree prune

Common gotchas

  • One branch, one worktree. Git won't check out a branch that's already checked out in another worktree. If main is open in your main folder, start new worktrees on new branches.
  • Only tracked files come across. A new worktree has no node_modules, virtual environment, .env file or build output, so the first build fails until you install or copy them. Setting up a new worktree covers dependencies, .env files, ports and databases.
  • Ports and databases are shared. Two worktrees running the same dev server try to bind the same port and write to the same local database unless you configure them apart.

Worktree, stash or second clone

ApproachWork on two branches at onceDiskTrade-off
Stash and switchNoNothing extraFine for a quick look; easy to lose track of stashes.
A second cloneYesA full copy of the historySlow to create, and branches only move between clones by push and fetch.
A worktreeYesThe checked-out files onlyQuick to create and shares commits instantly; needs its own dependencies.

Worktrees for coding agents

Two coding agents in one folder share its files and staging area, so one can overwrite the other's unfinished work. Give each agent its own worktree and branch and they can run side by side, each with a clean diff to review.

A separate folder stops agents overwriting each other's files, but two branches can still make incompatible changes. Review each diff, run your checks, and merge one at a time. Running coding agents in parallel walks through that workflow.

How ket does this

ket creates a worktree and a branch for every task, keeps them outside your repository, and can bring dependencies and .env files across from your main checkout, so you skip the create and copy steps above for each task. Its sidebar shows each worktree's agent and state, so you don't have to track which folder holds which agent, and the diff and merge are one step away. How ket manages worktrees.