Skip to main content
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.
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. 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: 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:
  • 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:
  • 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.
To give an AI agent its own branch, use -b, so it never takes over a branch that already exists:

List and remove worktrees

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.

Let coding agents create worktrees

A new repository’s AGENTS.md already tells coding agents how to use worktrees. If your AGENTS.md has no “Parallel agents” section, add this one:
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:
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.
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