Skip to main content
Every collaborator on a repository gets their own workspace — a private space where you can make changes without affecting anyone else. Workspaces keep your uncommitted work separate and synced to the cloud automatically. If you’re not familiar with the concept, check out the Repositories, Branches, and Workspaces page first.
We recommend using a separate workspace for each machine. Cloning the same workspace on multiple machines may lead to sync issues and data loss.

​
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.
For CLI usage, see clone command.

​
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. Seats are per user, not per machine: working from several computers with the same account does not use extra seats. Your machines stay in sync through commits. Uncommitted changes are uploaded to your own cloud workspace as you save, but a workspace on another computer does not get them until you commit. 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.
Don’t share a single workspace between machines via a cloud-synced folder (Dropbox, OneDrive, iCloud, Google Drive), a network drive, or by copying the .diversion directory. Each machine’s agent will fight over the workspace’s state, which can cause files to be deleted, sync loops, or repeated dv reset recoveries.

​
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, click Update to dv.commit.<id> in the workspace header, or run dv update. See Sync status.
  • Selective Sync decides what lands on disk. A folder left unchecked under the workspace menu’s Selective sync won’t download locally even when its files are committed. See Selective Sync.

​
Multiple workspaces on the same machine

You can keep more than one workspace of the same repo on one machine. For example, keep one workspace per branch, or one on each drive. This avoids switching branches in a large project. Each workspace syncs from its own folder.

​
Set up another workspace

1

Clone the repo again with a new workspace

On the dashboard (click the Diversion logo at the top left), open the Remote Repositories tab, click the … button at the right end of the repo’s row, and select Clone repo. In the Clone repository dialog, keep Select a workspace set to Create new workspace. Choose Create New Folder or Create from Existing Folder, click Browse… to pick a folder that is not inside a workspace, then click Clone.
2

Choose the folders to sync (optional)

Each workspace downloads its own files. To download less, click Choose… in the Folders to sync row and uncheck the folders you do not need. They are never downloaded. See Choose folders before cloning.
3

Switch to your branch

The new workspace starts on the default branch. Switch it in the branch selector, or run dv checkout <branch> in its folder.
With the CLI, clone straight onto your branch: dv clone <repo_id> <path> --new-workspace --ref <branch>. See clone command.

​
Copied workspace folder

If you run dv in a copy of a workspace folder while the workspace syncs from another folder, the command stops. The error message shows the folder that syncs now.

​
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 Organization settings, 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.
You can also rename a workspace from the workspace selector on the repo view: open the selector, click the … (more options) menu next to the workspace, and select Rename.
For CLI usage, see workspace command.

​
Deleting a workspace

1

Open the Workspaces page

Click your avatar and select Organization settings, 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.
You can also delete a workspace from the workspace selector on the repo view: open the selector, click the … (more options) menu next to the workspace, and select Delete.
For CLI usage, see workspace command.

​
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. Hover over the one you want to clone locally, click the … button at the right end of its row, and select Clone.
2

Choose the folders to sync (optional)

The clone dialog has a Folders to sync row showing the workspace’s current selection. Click Choose… to change it before the clone starts, so the folders you leave out are never downloaded. See Selective Sync.
3

Pick a directory

A directory picker opens — choose where you want the local copy to live on your machine.
4

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.
For CLI usage, see clone command.

​
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 Diversion logo at the top left), click Attach workspace at the top right, next to New repository.
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 starts syncing from this folder right away.
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.

​
If the workspace already syncs from another folder

A workspace syncs from one folder only. If you pick a copy of a workspace folder, for example one you copied to a new drive, the dialog shows the folder that the workspace syncs from now. Click Connect to sync the new folder instead:
  • Diversion stops syncing the old folder and removes its workspace settings (its .diversion directory). The files in the old folder stay on disk.
  • The workspace takes the content of the new folder. If a file is different in the two folders, Diversion uploads the version from the new folder. Uncommitted changes that exist only in the old folder are no longer in the workspace.
  • If Diversion cannot remove the old folder’s workspace settings, the confirmation message says so. The old folder is still not synced.
Click Cancel to keep syncing the old folder.

​
Change the folder name without re-cloning

You can change the folder name without re-cloning by following these steps:
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.
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. It has started successfully when you see Welcome to the interactive Diversion Shell.Alternatively, open the desktop app and click Start agent in the notice at the top right of the app.
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.
The workspace appears again on the Local Workspaces tab of the dashboard, with the new folder path.