Cloned vs. non-cloned workspaces
A workspace can be either cloned (local) or non-cloned (cloud-only). Understanding the difference helps you decide how to set up your workflow.
When to use a cloned workspace: Most of the time. If you’re actively developing — writing code, editing assets in a game engine, or using any local tools — you need a cloned workspace so those tools can access the files on disk.
When to use a non-cloned workspace: When you only need to browse files, review changes, or manage branches without editing locally. This is useful for lightweight access from a machine where you don’t want to download the full project, or for managing multiple workspaces without duplicating large repositories on disk.
You can clone a non-cloned workspace at any time — see Cloning a workspace locally below.
Creating a new workspace
In the Desktop App:1
Open the workspace selector
Open the workspace selector at the top-right of the repo view.
2
Click '+ New workspace'
This opens the Create New Workspace dialog.
3
Enter a workspace name
Give your workspace a descriptive name. This is required.In the desktop app, you can also check the Clone this workspace locally option to immediately create a local copy. If you choose to clone, you’ll need to pick a folder name and a directory on your machine.
4
Click 'Create' or 'Create & clone'
The workspace is created from the repository’s default branch. Once it’s ready, you’ll be navigated to the new workspace automatically.
Working from multiple computers
You can work on the same project from several machines — a desktop and a laptop, for example. Set up a separate workspace on each machine rather than sharing one. Your machines stay in sync through commits. Uncommitted local changes stay on the machine where they were saved — they are not uploaded to the cloud or visible from any other computer until you commit them. Once committed, every workspace tracking that branch picks them up automatically. To move uncommitted work between machines without committing, use Shelves, which are stored in the cloud and available from any workspace on the same repository.Set up a second machine
1
Install Diversion on the second machine
Sign in with the same account you use on your primary machine.
2
Create a new workspace on that machine
Follow the Creating a new workspace steps and clone it locally. Give it a name that identifies the machine (e.g.,
main-laptop) so you can tell your workspaces apart.3
Start working
Your new workspace syncs automatically. See Moving work between your machines below for how changes travel from one machine to the other.
Moving work between your machines
Work travels between your machines through commits:- Commit on the machine you’re working on. Only committed changes upload to the cloud, and only while sync is active — so commit your work (
dv commit -a -m "message"or the desktop app) and make sure sync isn’t paused. - Find the changes on the branch they were committed to. Each commit lands on a branch, and a workspace shows only the commits on the branch it’s currently on. To see changes you made on another machine, open the branch selector in the desktop app (or run
dv checkout <branch>) and switch to the branch they were committed to. - Let the workspace update. With auto-update on, the workspace pulls new commits automatically — just like a teammate’s workspace would. With it off, the sync status shows Updates available — click it, or run
dv update. - Selective Sync decides what lands on disk. A folder left unchecked under Settings -> Selective Sync won’t download locally even when its files are committed. See Selective Sync.
Workspaces on external storage
You can keep a cloned workspace on a USB drive, external SSD, or other detachable drive that mounts as a regular local disk. This lets you carry a workspace between machines without re-cloning, as long as each machine has Diversion installed and you’re signed in with the same account.1
Clone the workspace to the external drive
When cloning, pick a folder on the external drive as the local location.
2
Use it like any other workspace
With the drive connected and the Diversion agent running, the workspace syncs normally.
3
Re-attach after reconnecting the drive
If the workspace doesn’t appear after you plug the drive back in — or after you connect it to a different machine — use Attach workspace to point Diversion at the workspace folder on the drive.
Renaming a workspace
1
Open the Workspaces page
Click your avatar and select Your organizations, then click Repositories in the left sidebar and Workspaces in the repository column. Make sure the correct repository is selected in the picker at the top of the column. Find the workspace, click the actions menu at the end of its row, and select Rename.
2
Enter a new name
The Rename Workspace dialog shows the current name pre-filled. Type in the new name you’d like.
3
Click 'Rename'
The button is disabled if the name is empty or unchanged, so make sure you’ve actually typed something different.
Deleting a workspace
1
Open the Workspaces page
Click your avatar and select Your organizations, then click Repositories in the left sidebar and Workspaces in the repository column. Make sure the correct repository is selected in the picker at the top of the column. Find the workspace, click the actions menu at the end of its row, and select Delete.
2
Confirm deletion
The Delete Workspace dialog asks you to confirm. Keep in mind that all uncommitted changes in the workspace will be lost.
If the workspace is cloned locally, you’ll see an additional warning that your local files will remain on disk but will no longer sync with Diversion. You’ll need to check a confirmation checkbox before proceeding.
3
Click 'Delete'
This action is permanent — the workspace and any uncommitted changes are gone for good.
Cloning a workspace locally (Desktop only)
If you have a workspace that isn’t cloned to your machine yet, you can set up a local synced copy at any time.1
Open the workspace selector
Open the workspace selector at the top-right of the repo view. Workspaces that aren’t cloned on this machine appear under Remote. Select the one you want to clone locally.
2
Pick a directory
A directory picker opens — choose where you want the local copy to live on your machine.
3
Wait for sync
Diversion creates a local copy and keeps it synced automatically. Any changes you make locally will be reflected in the cloud workspace, and vice versa.
Attaching a workspace (Desktop only)
If you moved a repository to a different path on your machine, or if a workspace is not showing up after detaching a portable drive, you can re-attach it to Diversion.1
Click the 'Attach workspace' button
On the dashboard, click the Attach workspace button in the toolbar.
2
Browse to the workspace folder
A directory picker opens. Navigate to the folder containing your workspace (the folder with a
.diversion directory inside it).3
Click 'Connect'
Diversion will look up the workspace on the server and reconnect it. You’ll see a confirmation message once the workspace is successfully re-attached.
The workspace folder contains a hidden
.diversion directory that Diversion uses to track workspace state. This folder must remain in place and should not be modified or deleted. To verify it exists, enable hidden files in your file explorer (on Windows: View > Show > Hidden items; on macOS: press Cmd+Shift+.). If it is missing, or if the workspace was deleted from the server or you don’t have permission to access it, you’ll see an error message.Change the folder name without re-cloning
You can change the folder name without re-cloning by following these steps: This is the workspace we will use for the example:
1
Turn off the agent:
Right-click the Diversion icon in your system tray and select Quit, or end the dv.exe task in the Task Manager.Option a:
2
Rename the folder:
Change the folder name directly in your file explorer.
3
Restart the agent:
Run the command dv in your command line and verify it starts successfully. Alternatively, open the desktop app and click “start agent” when prompted.Option a:
4
Reattach your workspace:
Since the folder was renamed, the workspace will not be displayed. Click Attach workspace.
5
Connect to the new path:
Navigate to the path with the new folder name and click Connect.
