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 mainTo 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-searchThen 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 listMove one to another folder:
$ git worktree move ../myapp-review ../reviewRemove 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-loginIf you deleted a worktree's folder by hand, tell Git to forget it:
$ git worktree pruneCommon gotchas
- One branch, one worktree. Git won't check out a branch that's already checked out in another worktree. If
mainis 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,.envfile or build output, so the first build fails until you install or copy them. Setting up a new worktree covers dependencies,.envfiles, 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
| Approach | Work on two branches at once | Disk | Trade-off |
|---|---|---|---|
| Stash and switch | No | Nothing extra | Fine for a quick look; easy to lose track of stashes. |
| A second clone | Yes | A full copy of the history | Slow to create, and branches only move between clones by push and fetch. |
| A worktree | Yes | The checked-out files only | Quick 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.
Related guides
Set up a Git worktree for a coding agent.
Dependencies, .env files, ports and databases: what a fresh worktree is missing and how to fill it in.
Run coding agents in parallel without sharing a working directory.
How to split work between agents, watch them, and merge the results one at a time, smallest dependency first.
Run multiple Claude Code sessions in parallel.
The commands for running Claude Code sessions in parallel, each in its own worktree.