> ## Documentation Index
> Fetch the complete documentation index at: https://docs.diversion.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Worktrees

> Work on the same repository in several directories at once

A worktree is an extra clone of your repository, with its own workspace, in another directory on the same computer. Use one to work on two tasks at the same time without switching branches. For example, fix a bug while a long build runs in your main clone, or give each AI agent its own directory.

## Save downloads and disk space

An extra worktree on a Windows Dev Drive or a Mac takes almost no extra disk space and downloads almost nothing. Files that your clone already has are not downloaded again, and they share disk space with the clone's files. A file uses its own disk space only after you change it. New commits, branch switches, and merges also download each file once per disk, not once per worktree. Files are shared only between clones of the same repository.

> [!NOTE]
>
> **Prerequisite:** to save disk space and downloads, the worktree must be on a Windows Dev Drive or a Mac (APFS) disk, on the same disk as the clone. On other disks, worktrees still work, but each one downloads every file.

### Windows: use a Dev Drive

1. [Create a Dev Drive](https://learn.microsoft.com/windows/dev-drive/). It uses the ReFS file system, which supports this.
2. Clone the repository onto the Dev Drive.
3. Create worktrees from that clone. By default they go next to the clone, so they are on the same drive.

### macOS and Linux

* **macOS**: APFS, the default disk format, supports this. You do not need to set anything up.
* **Linux**: each worktree downloads every file. Copy-on-write support is coming soon.

## A worktree is a workspace

Every clone on your computer is a [workspace](https://docs.diversion.dev/concepts/repo-branch-workspace.md): a private place for your uncommitted changes, synced to the cloud as you save. A worktree is one more workspace of the same repository, cloned into another directory.

* A worktree shows in the workspace list and syncs like any clone.
* Each worktree has its own uncommitted changes, and you commit from it as usual.
* By default, each worktree gets its own branch. With `--ref`, several worktrees can be on the same branch, and a commit from one reaches the others automatically.

## Create a worktree

Run `dv worktree add` from inside your clone:

```bash theme={null}
dv worktree add my-task            # on branch my-task; creates it if it does not exist
dv worktree add -b my-task         # on a new branch my-task; fails if the branch exists
dv worktree add --ref fix-login    # on an existing branch, a commit, or a tag
```

* A new branch starts from your clone's current commit. With `-b` and `--ref` together, it starts from the `--ref` commit instead.
* `dv worktree add` needs a name, `-b`, or `--ref`. With none of them, it stops and asks for a name.

The worktree goes into `diversion-worktrees/<repo>/<name>`, next to your clone. With no name, the directory is named after the branch or commit. For example, from `~/projects/game`:

```
~/projects/
  game/                          your clone
  diversion-worktrees/
    game/
      fix-login/                 dv worktree add --ref fix-login
      my-task/                   dv worktree add my-task
```

* A worktree cannot be inside the clone. To use another location, give a path outside it, such as `../my-task`.
* Keep worktrees on the same disk as the clone, so they can share file content with it. See [Save downloads and disk space](#save-downloads-and-disk-space).

To give an AI agent its own branch, use `-b`, so it never takes over a branch that already exists:

```bash theme={null}
dv worktree add -b agent-1
```

## List and remove worktrees

```bash theme={null}
dv worktree list
dv worktree remove <path> [-f]
```

`dv worktree list` shows the worktrees of this repository on this computer, with their path, branch, and workspace ID.

`dv worktree remove` deletes the worktree's workspace, stops syncing its directory, and then deletes the directory. It does not ask for confirmation, but it refuses to remove a worktree that may hold work:

* uncommitted changes or conflicts. It first rescans the worktree and waits for the sync, so a file you saved a moment ago counts.
* conflict backups, which are never uploaded
* a submodule inside the worktree
* a paused worktree, whose changes may not be synced. Resume it with `dv workspace resume`.

Commit or clear that work, or add `-f` to delete the worktree with it. If deleting the workspace fails, run the command again. If only deleting the directory fails, delete it by hand.

`dv worktree remove` does not remove your main clone; to stop syncing a clone, use [`dv unregister`](https://docs.diversion.dev/cmd-ref/unregister).

## Let coding agents create worktrees

A new repository's [`AGENTS.md`](https://docs.diversion.dev/basic/start-using-diversion#agents-md-and-claude-md) already tells coding agents how to use worktrees. If your `AGENTS.md` has no "Parallel agents" section, add this one:

````markdown theme={null}
## Parallel agents

Give each agent that works in parallel its own worktree: a second checkout of
this repository with its own workspace. Agents then cannot see or overwrite
each other's uncommitted changes.

```sh
dv worktree add -b task-name          # Create a worktree on a new branch task-name; it prints the worktree path
dv worktree list                      # List this repository's worktrees
dv worktree remove <path>             # Delete a worktree and its workspace; refuses if it has uncommitted changes
```

- Work only in the worktree path. The shell can return to the original
  directory after each command, so start every command with
  `cd <worktree path> &&`, and use absolute paths for file edits.
- The worktree is outside this directory, so file edits there may need the
  user's approval. In Claude Code, after the first worktree exists, the user
  can run `/add-dir` once on the `diversion-worktrees` directory next to this
  one.
- Commit in the worktree, on its own branch. Merge into the target branch only
  when asked.
- Claude Code's `isolation: worktree` option works only with git or a
  WorktreeCreate hook. Without one, use the commands above.
````

Claude Code reads `AGENTS.md` only when `CLAUDE.md` imports it. Make sure `CLAUDE.md` at the root of the repository has the line `@AGENTS.md`, and create the file if it does not exist.

## Set up new worktrees automatically

A new worktree has the repository's files, but not what you build or install locally, such as dependencies or a build cache. To prepare it, commit a `.dvworktree.yml` file at the root of the repository:

```yaml theme={null}
# Dirs to symlink from the clone you run the command in, instead of building them again
link:
  - node_modules
  - .cache/build
# Shell command to run in the new worktree
setup: ./scripts/bootstrap.sh
```

Both parts are opt-in:

* `--link` symlinks each dir under `link:` from the clone you run the command in.
* `--setup` runs the `setup:` command in the new worktree. The command gets the path of the clone you ran it from in the `DV_WORKTREE_ORIGIN` environment variable.

```bash theme={null}
dv worktree add --ref fix-login --link --setup
```

> [!WARNING]
>
> The file comes from the branch or commit you check out. Use `--setup` only with refs you trust, because it runs a command from that ref on your computer.

## Compared with git worktree

| | `git worktree` | `dv worktree` |
| - | - | - |
| Uncommitted changes | Only on your disk | Backed up to your cloud workspace as you save |
| New commits on the branch | Pull or merge in each worktree | Arrive automatically in every worktree |
| Same branch in two worktrees | Refused unless you use `--force` | Allowed with `--ref`; a commit in one reaches the other |
| Files on disk | A full copy of every file per worktree | Shared with the clone on a Dev Drive or a Mac, until you change them |
| Remove | Deletes the directory | Also deletes the workspace |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.