Key terms
- Mount path — the folder in the parent repo where the other repo appears, for example
libs/engine. - Pin — the commit of the mounted repo that the parent points to. The pin is part of the parent’s history, so everyone who syncs the parent gets the same version.
- Child workspace — the working copy of the mounted repo that Diversion creates inside the mount path. It is a real workspace: you can check out a branch, edit, and commit in it.
Add a submodule
From anywhere inside the parent workspace:<repo> is the mounted repo’s name or ID. The files appear at libs/engine, and the pin is
committed in the parent, so teammates get the submodule when they sync.
Diversion refuses to mount over a folder that already has files, on a symlink, or at a path
that differs from an existing mount only by letter case (such paths open the same folder on
Windows and macOS).
See what state your submodules are in
synced— the local mount is at the pinned commit.missing— the pointer exists but the files were not created locally yet (for example, right after cloning the parent). Rundv submodule update.pin_mismatch— the local mount is at a different commit than the pin, usually after committing inside the mount.
LOCAL CHANGES counts uncommitted changes inside the child workspace. It shows paused
when the child workspace’s sync is paused, because a paused workspace cannot report its
changes.
The parent’s regular dv status also warns when any submodule needs attention:
Get or repair the files
update makes the local mounts match the pins: it clones missing mounts, moves drifted
mounts back to the pinned commit, and re-creates a mount folder that was deleted.
A mount that is checked out on a branch is moved to the pinned commit and detached.
Your commits stay on the branch; run dv checkout <branch> inside the mount to continue
working on it.
A mount with uncommitted changes is never touched. When updating everything, such a mount
is skipped and reported, and the others still update:
Update submodules automatically
Run this inside the parent workspace:dv submodule update for you on each mount whose
pin changed. This covers a checkout of another branch or commit in the parent, and a
teammate’s repin that syncs to your workspace. The update starts a few seconds after the
parent finishes syncing. The setting is per workspace and is off by default. Turning it on
updates every mount once.
- A mount whose pin did not change is not touched, so a branch you checked out inside it stays.
- The rules of
dv submodule updateapply: a mount on a branch is moved to the new pin and detached, and a mount with uncommitted changes is not touched. - A mount that could not be updated shows in
dv statusas not on its pinned commit. Rundv submodule updateafter you commit or revert its changes. - The update runs in the background. A script that needs the files right after a checkout should run
dv submodule update, which waits for them.
Work inside a submodule and move the pin
The mount is a working clone. To change the mounted repo and point the parent at the result:repin moves the pin of an existing submodule. Without --ref it pins the child
workspace’s current commit — what you just built and tested. To pin something else, pass a
branch name, commit ID or tag ID. A branch pins its current tip; the pin does not follow the
branch afterwards:
Remove a submodule
update, it refuses while the mount holds
uncommitted work.
Good to know
- Commands run inside the mount apply to the mounted repo, not the parent.
dv statusinlibs/engineshows the child’s changes. - Edits inside the mount never show up as parent changes; the parent repo stays clean.
- The child workspace is named
<folder> submodule @ <your machine>in the workspace list, so it is easy to tell apart from a regular clone. - In the web app, the parent’s file tree shows a mount with a tree icon and a tooltip naming the mounted repo and its pinned commit.
- The pin is part of the parent’s history. Branching, merging, and going back in time in the parent carry the pin with them like any other change.

