How to use Git worktrees

You are halfway through a feature when a production bug lands. The usual options are all awkward: stash your work, commit something half-finished, or clone the repository a second time. A Git worktree is the cleaner answer. It gives you a second working directory, with its own checked-out branch, that shares the same repository.

This tutorial covers creating, using, and removing worktrees, a hotfix recipe, and why worktrees have become the standard way to run several AI coding agents on one repository at the same time.

What a worktree is

A normal repository has one working directory, tied to one checked-out branch. git switch changes which branch that directory shows, and anything uncommitted gets in the way.

A worktree is an extra working directory attached to the same repository. Each worktree has its own checked-out branch, its own index and its own uncommitted changes. They all share one set of commits, branches, tags and remotes. A commit made in one worktree is immediately visible to the others, and a git fetch in one updates them all.

Compared with a second clone, a worktree:

• does not copy the history, so it is quick to create and light on disk
• stays in sync with no extra git fetch or git pull between copies
• cannot drift onto a different set of remotes

Create a worktree

From inside your repository:

git worktree add ../site-hotfix hotfix/login

This checks out the existing branch hotfix/login into a new folder, ../site-hotfix, next to your current one.

To create a new branch at the same time, use -b:

git worktree add -b feature/search ../site-search main

That creates feature/search from main and checks it out in ../site-search. If you leave off the starting point, the new branch starts from your current HEAD.

Put worktrees outside the repository folder, as siblings, so the main working directory never contains another checkout.

List your worktrees

git worktree list

/home/dev/site           4f1c2a8 [main]
/home/dev/site-hotfix    9b2e7d1 [hotfix/login]
/home/dev/site-search    c3a9f50 [feature/search]

Each line shows the folder, the current commit and the branch.

One rule: a branch can only be checked out once

Git will not let two worktrees have the same branch checked out. This protects you from changing a branch in one place and having it move under you in another.

fatal: 'main' is already used by worktree at '/home/dev/site'

If you need a second copy of the same commit, create a new branch for it, or check out the commit detached:

git worktree add --detach ../site-inspect v2.3.0

Recipe: a hotfix without touching your work

You are on feature/search with uncommitted changes. Production needs a fix.

git worktree add -b hotfix/payment-race ../site-hotfix main
cd ../site-hotfix
# fix, test, commit
git push -u origin hotfix/payment-race

Your feature work, including the uncommitted files, is exactly where you left it. When the fix is merged and deployed, remove the worktree (see below) and carry on.

Remove a worktree

When you are finished:

git worktree remove ../site-hotfix

Git refuses if the worktree has uncommitted or untracked changes. Add --force only when you are sure you want to discard them. The branch itself is not deleted. Delete it separately with git branch -d hotfix/payment-race once it is merged.

If you deleted a worktree folder by hand, Git still has a record of it. Clear stale records with:

git worktree prune

Things that are not shared

A worktree shares Git data, not everything on disk. Each new worktree starts as a clean checkout of tracked files, so:

• Ignored files are missing. node_modules, vendor, build output and .env files are not copied. Install dependencies and recreate your env file in each worktree.
• Ports and local services collide. Two dev servers on port 3000 will fight. Give each worktree its own port, or its own container names.
• Hooks and config are shared. Settings in the repository's .git folder apply to every worktree.

Worktrees and parallel AI coding agents

A coding agent edits files in whatever directory it runs in. Run two agents in the same directory and they overwrite each other's changes, and each one's test run sees the other's half-finished code.

Worktrees remove that problem. Give each agent its own worktree and branch:

git worktree add -b agent/fix-tests ../site-agent-tests main
git worktree add -b agent/update-docs ../site-agent-docs main

Start one agent in each folder. They cannot touch each other's files, each one commits to its own branch, and you review the results as ordinary branches and pull requests. Merge what you accept and remove the rest.

Two habits make this work well:

• Keep tasks independent. Two agents editing the same file in different worktrees still produce a merge conflict later. Split work by area, not by step.
• Treat each branch like any pull request. Agent output goes through the same review and checks as human work. Our guide to committing AI-generated code covers what to look for, and resolving merge conflicts with AI helps when branches do collide.

For the wider picture of how coding agents fit into a deployment workflow, see how AI coding assistants are changing the way we deploy code and CLIs or MCP for coding agents.

Quick reference

Next steps

• How to create a Git branch: the branch commands worktrees build on
• Branching and merging: bring finished work back together
• Cherry-picking commits: move a fix between branches
• Reverting and undoing commits: when a change needs to come back out

Every branch you push from a worktree can be deployed on its own. DeployHQ matches branch names such as main or release/* and deploys on every push, so a hotfix branch can reach a staging server for checking before it merges. Start deploying free.

Questions? Email support@deployhq.com or find us on X at @deployhq.