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:

```bash
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`:

```bash
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

```bash
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:

```bash
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.

```bash
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:

```bash
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:

```bash
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:

```bash
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](/git/committing-ai-generated-code) covers what to look for, and [resolving merge conflicts with AI](/git/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](https://www.deployhq.com/blog/ai-coding-assistants-deployments) and [CLIs or MCP for coding agents](https://www.deployhq.com/blog/clis-or-mcp-for-coding-agents-practical-comparison).

## Quick reference

| Goal | Command |
|---|---|
| Add a worktree for an existing branch | `git worktree add <path> <branch>` |
| Add a worktree with a new branch | `git worktree add -b <new> <path> <start>` |
| Add a detached worktree | `git worktree add --detach <path> <commit-or-tag>` |
| List worktrees | `git worktree list` |
| Remove a worktree | `git worktree remove <path>` |
| Force removal | `git worktree remove --force <path>` |
| Clean up stale records | `git worktree prune` |

## Next steps

- [How to create a Git branch](/git/creating-a-branch): the branch commands worktrees build on
- [Branching and merging](/git/branching-and-merging): bring finished work back together
- [Cherry-picking commits](/git/cherry-picking-commits): move a fix between branches
- [Reverting and undoing commits](/git/reverting-commits): when a change needs to come back out

---

Every branch you push from a worktree can be deployed on its own. [DeployHQ](https://www.deployhq.com/features/automatic-deployments) 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](https://www.deployhq.com/signup).

Questions? Email [support@deployhq.com](mailto:support@deployhq.com) or find us on X at [@deployhq](https://x.com/deployhq).