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
- Create a Dev Drive. It uses the ReFS file system, which supports this.
- Clone the repository onto the Dev Drive.
- 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
Rundv worktree add from inside your clone:
- A new branch starts from your clone’s current commit. With
-band--reftogether, it starts from the--refcommit instead. dv worktree addneeds a name,-b, or--ref. With none of them, it stops and asks for a name.
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.
-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.
-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’sAGENTS.md already tells coding agents how to use worktrees. If your AGENTS.md has no “Parallel agents” section, add this one:
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:
--linksymlinks each dir underlink:from the clone you run the command in.--setupruns thesetup:command in the new worktree. The command gets the path of the clone you ran it from in theDV_WORKTREE_ORIGINenvironment variable.

