# Diversion Documentation > This file is very large and may be truncated. For an index of this content, please refer to https://docs.diversion.dev/llms.txt instead. # Resolve Conflicts with AI Source: https://docs.diversion.dev/advanced/ai-conflict-resolution Let AI propose a resolution for text files with merge conflicts, then review it before you complete the merge. When a merge, update, or revert has conflicts in text files, AI can resolve them for you. For each file, AI reads both versions, the version they started from, and the commit messages on both sides. Then it writes a merged file that keeps the intent of both changes, and it explains what it kept. You stay in control: in the Diversion app, nothing is committed until you review the result and click **Complete merge**. > [!NOTE] > > Resolving conflicts with AI is available on **Professional**, **Studio**, and **Enterprise** plans, and during a trial. ## Resolve conflicts in the Diversion app **1. Open the merge** Start the merge as usual (see [Working in parallel](/basic/working-in-parallel#how-to-merge)). If there are conflicts, the conflict screen opens. **2. Ask AI to resolve** * To resolve one file, select it and click **Resolve with AI** above the file. * To resolve many files, click **Resolve N text files with AI** above the file list. To pick only some files, tick their checkboxes first. Resolve related files in one request: AI sees the conflicts in all the files of a request, so it can keep the changes consistent across them. **3. Wait for AI** Each file shows **AI queued** or **AI working**. A file is read-only while AI works on it. You can keep resolving other files in the meantime. To stop, click **Stop** above the file list, or **Stop AI and resolve manually** above the file. **4. Review the result** A resolved file shows **Resolved by AI** and a short reason for the result. Read the merged file. If you do not agree with the result, open **Resolved by AI · Change** to choose a side or go back to the conflict, or edit the file. **5. Complete the merge** Resolve any files that are left, type a commit message, and click **Complete merge**. The footer shows how many files AI resolved. ### When AI cannot resolve a file Sometimes the two changes cannot be combined safely, for example when both branches changed the same function in different ways. Then the file shows **AI couldn't resolve this file** and the reason. The file stays unresolved, and you resolve it yourself. If you already changed a file and then ask AI to resolve it, Diversion asks before AI replaces your changes. ## Resolve conflicts from the CLI Add `--conflict_resolution ai` to `merge`, `update`, or `revert`: ```bash theme={null} dv merge --conflict_resolution ai ``` 1. Diversion first merges what it can on the server. 2. AI resolves the text files that still have conflicts, and the CLI shows its progress. 3. If AI resolves every conflict, Diversion completes the merge and creates the commit. 4. If some conflicts are left, the merge stays open. The CLI lists them and prints a link to finish the merge in the Diversion app. The files AI resolved stay resolved. > [!WARNING] > > From the CLI, the merge completes without a review step when AI resolves every conflict. To review each result first, use the Diversion app, or check the merge commit after it is created. To stop waiting, press `Ctrl+C`. AI keeps working on the server, and you can finish the merge in the app. ## Plans and limits * **Plans:** Professional, Studio, and Enterprise, and during a trial. * **Text files only:** AI skips binary files, such as images, models, and `.uasset` files, and Unity YAML files, such as scenes and prefabs. For these, choose a side or use an [external merge tool](/advanced/external-merge-tools). * **Both sides need the file:** if one side deleted the file, or two different files were moved to the same path, you choose which version to keep. * **File size:** 256 KB or less on both sides. For a larger file, AI shows that the file is too large, and you resolve it yourself. * **Files at a time:** up to 50. For a merge with more files, click the button again after the first files are done. The CLI does this for you. * **Usage limit:** each organization has a usage limit for AI. If your organization reaches it, AI shows "The AI token budget is used up for now. Try again later." The limit resets after a few hours. ## Your data AI runs only when someone on your team asks it to resolve conflicts. Diversion then sends the conflicting files and their commit messages to a trusted third-party AI provider, through Diversion. You do not need your own API key. # AI Reviews with SlothBot Source: https://docs.diversion.dev/advanced/ai-reviews Ask SlothBot to check changed code and leave findings alongside your human reviewers. SlothBot checks the changes in a review for bugs and leaves comments on the code. It can read related files in the repository to understand how the changes fit together. Human reviewers can keep reviewing while SlothBot works. > [!NOTE] > > AI reviews are available on **Studio** and **Enterprise** plans, and during an active trial or grace period. Your organization must have SlothBot enabled. ## Request a review in the app 1. [Create a review](/basic/reviews#creating-a-review) between two branches, or open an existing one. 2. Add a title and description that explain the intent of the changes. SlothBot uses them as context. 3. On the review's **Conversation** tab, click **Review with SlothBot** below the **Reviewers** list, to the right of the description. 4. Wait for the queued and reviewing states to finish. You can leave the page; SlothBot runs on the server. 5. Read the findings in **Conversation** and **Files changed**. When the review finishes, the button reads **Reviewed by SlothBot**, and the line under it shows the number of files reviewed, findings and files skipped, and the commit SlothBot checked. You need write access to the repository and read access to all its files. The review must be open and compare two branches. When SlothBot finds no issues in the files it reviewed, it leaves a short summary comment. A review with only skipped files can finish without a comment. SlothBot does not approve, merge, or change your code. Check its findings before acting on them; it can miss bugs or report something that is not a bug. To find reviews that SlothBot has checked, choose **SlothBot** in the Reviews list's **Reviewer** filter. Use the thumbs-up or thumbs-down reaction on a SlothBot comment to share whether it was helpful. Click the same reaction again to remove it. ## Request a review from the CLI From your feature branch, create a review and request SlothBot: ```bash theme={null} dv review "Handle missing configuration" --reviewer "@slothbot" ``` To request both SlothBot and a teammate, use a comma-separated list: ```bash theme={null} dv review "Handle missing configuration" --reviewer "@slothbot,teammate@example.com" ``` Request SlothBot on an existing review: ```bash theme={null} dv review edit --add-reviewer "@slothbot" ``` Check the status: ```bash theme={null} dv review view ``` The request returns while SlothBot works. Open the printed review link to read its comments. If the AI request fails after the review was created, the review still exists; use `review edit` to retry. See the [review command reference](/cmd-ref/review) for other options. ## Review new changes After committing more changes to the review branch, request SlothBot again. Reviews do not rerun automatically. Each result identifies the commit it checked. A completed result is reused when the compared changes are unchanged. Editing only the review title or description does not start a new AI review. Earlier comments remain in the conversation after new commits; their inline locations may no longer appear. ## Limits and failures * **Text files:** binary files, including images, models, and Unreal assets, are skipped. Files larger than 512 KB on either side are also skipped. * **Large changes:** file and input-size limits can leave some files unreviewed. Check the skipped-file count and use smaller reviews when possible. * **Repository context:** SlothBot can read related files, but does not run the code or tests and does not search the contents of the entire repository. * **Usage:** AI reviews share your organization's AI token budget. If it is exhausted, wait and try again later. * **Failed runs:** the review page shows an error. Retry with **Review with SlothBot** after addressing it. If the branch changed while SlothBot was working, request a review of the latest changes. If the button is missing, check with your organization admin that SlothBot and AI reviews are available for your organization. A plan upgrade does not override an organization setting that disables SlothBot. ## Your data SlothBot runs when someone requests a review. Diversion sends the changed code, selected repository context, review title and description, and earlier review comments to a third-party AI provider. You do not need your own API key to use AI reviews in Diversion's cloud service. # File Preview Source: https://docs.diversion.dev/advanced/asset_preview Preview 3D models, Unreal assets, Photoshop files, audio, images and code directly in Diversion Click any supported file in Diversion to preview it instantly—no need to open external applications. When a file changes, diffs and reviews show the old and new versions side by side. ## Asset Previews Preview 3D models, Unreal Engine assets, Photoshop files and audio up to **25 MB** in size. > [!NOTE] > > Asset previews are available on the **Professional** plan and above. They are currently in an open trial, so every plan can use them. See [Choosing your plan](/choosing-your-plan). ### 3D Models Preview and inspect 3D models with an interactive viewer. Drag to rotate the camera around your model, scroll to zoom, and right-drag to pan. The toolbar above the model switches between **Wireframe**, **Unlit** and **Shaded**, and **Reset view** returns the camera to its starting position. In a diff, **Sync view** moves the cameras on both sides together. **Supported formats:** * .gltf, .glb * .fbx * .obj ### Unreal Engine Assets Preview `.uasset` files by extracting their embedded thumbnails. ### Photoshop Files Preview `.psd` files. Diversion shows the flattened image saved in the file, not individual layers. Some Photoshop files may not be previewable. ### Audio Play audio files in the file viewer. The format and duration show under the player. **Supported formats:** .wav, .mp3, .ogg ## Images and Text Preview images and text files up to **2 MB** in size. ### Images **Supported formats:** .jpg, .jpeg, .png, .gif, .webp, .tif, .tiff, .bmp, .ico, .svg ### Text and Code Any text file opens in a code viewer. Syntax highlighting covers common languages such as C++, C# and JSON, plus these Unreal Engine and shader formats: * .uproject, .uplugin, .uprojectdirs * .usf, .ush (Unreal Shader Format) * .glsl, .hlsl * .ispc, .isph * .udn # Cache Servers Source: https://docs.diversion.dev/advanced/cache-servers Choose which cache server this computer downloads files from > [!NOTE] > > Cache servers are an Enterprise feature. If your deployment has none, see the [pricing page](https://www.diversion.dev/pricing). A cache server keeps a copy of your repository files close to your team, for example inside an office network. Large downloads come from the cache instead of the main storage, so they finish faster. ## How a cache server is chosen The Diversion agent on each computer gets the list of cache servers from your deployment. * With one cache server, the agent uses it. * With several, the agent measures the response time of each one and uses the fastest. * If a cache server stops answering, downloads fall back to the main storage until the cache is healthy again. This is the **Automatic** mode, and it is the default. ## Pin a cache server You can pin one cache server instead of letting the agent choose. This helps when you are on a VPN, when you test a new cache server, or when the measured response time does not match real download speed. The pin is an agent setting, so it applies to the current computer only. It survives agent restarts, and the desktop app and the command line show and change the same setting. ### In the desktop app **1. Open your profile** Click your avatar in the top right corner and choose **Your profile**. **2. Find the This computer section** The **This computer** section is shown only in the desktop app, because it controls the agent running on this computer. It is not shown in the browser. **3. Choose a cache server** In **Cache server**, choose one of: * **Automatic**: the agent picks the fastest cache server. The menu shows which one is in use now. * A cache server from the list your deployment advertises. * **Custom URL**: type the `http(s)` address of a cache server and click **Apply**. The setting is saved on the agent right away. If the section says the Diversion agent is not reachable, start the agent (open the desktop app or run any `dv` command) and reload the page. ### From the command line ```bash theme={null} dv blob-cache # show the pinned, active, and available cache servers dv blob-cache set # pin a cache server by name or http(s) URL dv blob-cache clear # go back to Automatic ``` A pin by name must match a cache server your deployment advertises. A pin by URL can point at any `http(s)` cache server. # Claude Code session transcripts Source: https://docs.diversion.dev/advanced/claude-code-session-transcripts Install the Diversion plugin for Claude Code, stop it from recording, and delete the session transcripts it recorded. The [Diversion plugin for Claude Code](https://github.com/DiversionCompany/diversion-claude) records the transcript of each Claude Code session and links it to your commits. You can delete these transcripts yourself in the Diversion web app. Your files and commits do not change. > [!NOTE] > > This page is available on Diversion cloud. On a self-hosted install, contact support. ## Install the plugin Before you start: * Install Diversion, so that `dv` is on your `PATH`. See the [Quickstart](/quickstart). * Start Claude Code from your Diversion workspace folder, or a folder inside it. Inside Claude Code, run: ``` /plugin marketplace add DiversionCompany/diversion-claude /reload-plugins /plugin install diversion@diversion ``` Then quit Claude Code (`/quit`) and start it again from your workspace folder: ```bash theme={null} cd path/to/your/workspace claude ``` ## Stop recording While the plugin is on, it records new sessions again. Turn it off before you delete, on each computer where you use it. Inside Claude Code, run: ``` /plugin disable diversion@diversion ``` To remove the plugin completely, run `/plugin uninstall diversion@diversion` instead. Then restart Claude Code, so that sessions that are already open stop recording too. ## Delete your transcripts **1. Open Settings > AI** Open [Settings > AI](https://app.diversion.dev/settings/ai) in the Diversion web app. The page shows **Delete Claude Code session transcripts**. **2. Choose where to delete** * Choose **All repositories** to delete every transcript you recorded. * Or choose **Specific repositories**, then pick them in **Choose repositories**. Each repository shows how many sessions it has. You can choose up to 10 repositories in one request. **3. Delete** Click **Delete sessions**, then **Delete** to confirm. **4. Wait for it to finish** The page shows the progress while it deletes. When it is done, you see **Claude Code sessions deleted**. If you chose **All repositories**, the page then shows "You have no recorded Claude Code sessions." If you see "The deletion stopped before it finished. Try again.", click **Delete sessions** again. > [!WARNING] > > You cannot undo the deletion. ## What gets deleted * The deletion removes your recorded sessions, their transcripts, and their checkpoints in the repositories you chose. * It applies to your Diversion account: it deletes the transcripts recorded on all your computers, with any Claude account. * Other users' transcripts do not change. * Your files and commits do not change, but your commits no longer show a transcript. # External Merge Tools Source: https://docs.diversion.dev/advanced/external-merge-tools Resolve merge conflicts with your own merge tools, such as UnityYAMLMerge, KDiff3, or Meld. When a merge has conflicts, Diversion can run a merge tool that you choose on each conflicting file. The tool merges the two versions of the file, and Diversion saves the result to the merge. Use this for files that need a special merge tool, for example: * Unity scenes and prefabs, with UnityYAMLMerge (Unity Smart Merge) * JSON, YAML, or source code, with a syntax-aware tool such as mergiraf * Any file that you want to merge by hand in a visual tool, such as KDiff3 or Meld ## Quick start You set up your tools once per computer, then use them in each merge. Each step can be done in the desktop app or with the CLI. **1. Install the merge tool on your computer** For example, install [mergiraf](https://mergiraf.org) to merge JSON files. For Unity and other tools, see [Examples](#examples). **2. Add the tool to Diversion** Tell Diversion which files the tool handles and how to run it. * **Desktop app:** open **Settings > Merge tools** and add a tool with these values. See [Set up tools in the desktop app](#set-up-tools-in-the-desktop-app). * **Name:** `mergiraf` * **File pattern:** `\.json$` * **Command:** `mergiraf merge $ANCESTOR $CURRENT $INCOMING -o $RESULT` * **CLI:** run `dv merge-tool add`: ```bash theme={null} dv merge-tool add --name mergiraf --pattern '\.json$' --cmd 'mergiraf merge $ANCESTOR $CURRENT $INCOMING -o $RESULT' ``` Both save the same list of tools, so a tool you add in one place also works in the other. **3. Start the merge** * **Desktop app:** start the merge as usual. When it has conflicts, click **View conflicts** to open the merge screen. * **CLI:** add the `merge-tool` conflict resolution: ```bash theme={null} dv merge --conflict_resolution merge-tool ``` **4. Resolve conflicts with the tool** Diversion first merges what it can on the server. A tool runs only on the conflicts that are left. * **Desktop app:** select a conflicting file, then click **Resolve with \**. You run the tool one file at a time. See [From the Diversion desktop app](#from-the-diversion-desktop-app). * **CLI:** Diversion runs the matching tool on each conflict, one after another. If a conflict is still open at the end, finish it in the Diversion app. See [From the CLI](#from-the-cli). ## How it works 1. You start a merge, update, or revert. 2. Diversion first merges what it can on the server. If the two sides changed different parts of a text file, Diversion merges it for you, and no tool runs. 3. For each conflict that is left, Diversion finds the first tool whose pattern matches the file path. It downloads the versions of the file to temporary files and runs the tool. In the desktop app, this happens when you click **Resolve with \**. With the CLI, it happens for every conflict. 4. When every conflict is resolved, you complete the merge. In the desktop app, click **Complete merge**. The CLI completes the merge for you. 5. If some conflicts are not resolved, the merge stays open. You resolve the rest in the Diversion app. The conflicts that the tools resolved stay resolved. > [!NOTE] > > Merge tools run on your computer. Your tool settings are saved for your user on this computer, not in the repository, so each team member sets up their own tools. ## Set up a merge tool **1. Install the tool** Install the merge tool and find the full path to its program. If the program is on your `PATH`, the program name is enough. **2. Add the tool to Diversion** Tell Diversion which files the tool handles and how to run it: ```bash theme={null} dv merge-tool add --name --pattern '' --cmd '' ``` See [Examples](#examples) for ready-to-use commands. **3. Check your setup** List your tools, in the order Diversion matches them: ```bash theme={null} dv merge-tool ``` ### Set up tools in the desktop app In the desktop app, open **Settings > Merge tools**. The page shows the same tools as `dv merge-tool`, in the order Diversion matches them. A change on the page also changes the tools that the CLI uses. **1. Start editing** Click the edit (pencil) button in the table header. If you have no tools yet, click **Add merge tool**. **2. Add a tool** Click **+**, then fill in the new row: * **Name**: a name that no other tool has. * **File pattern**: a regular expression for the file path, the same as `--pattern`. See [File patterns](#file-patterns). * **Command**: the same as `--cmd`. It must include `$RESULT`. To pick the program, click the folder button. The app puts the program path, in double quotes, at the start of the command. * **Result check**: **Tool's exit code** (the default), or **Diversion checks the result** for a tool that you would add with `--no-trust-exit-code`. See [Exit codes and visual tools](#exit-codes-and-visual-tools). **3. Set the order** Drag the rows to change the order. Diversion checks the tool with **Priority** 1 first. **4. Save** Click **Save changes**, then click **Save** in the dialog. To check your setup, enter a file path under **Which tool runs for a file?**, for example `Assets/Scenes/Main.unity`. The page shows the tool that runs for this file, or `No tool matches this file`. Rules on the settings page: * Type the command without outer quotes. The CLI needs them only for your shell. To use a command from [Examples](#examples), copy the value of `--cmd` without its outer quotes. In the Windows examples, also change each `\"` to `"`. * To delete a tool, click its delete button. Until you save, you can click the undo button to keep the tool. * **Save changes** stays off while a row has an error, for example a command without `$RESULT`. * If someone changes the tools with `dv merge-tool` while you edit, the save fails. Click **Cancel**, then make your changes again. ### Command placeholders In `--cmd`, use these placeholders for the file paths. Diversion replaces them with temporary files before it runs the tool. | Placeholder | Replaced with | | - | - | | `$ANCESTOR` | The common ancestor: the file before either side changed it | | `$CURRENT` | Your side: the branch you merge into, or your workspace for `update` and `revert` | | `$INCOMING` | The incoming side: the branch or commit you merge in, the latest branch version for `update`, or the reverted content for `revert` | | `$RESULT` | The output file. The tool must write the merged result here. It starts empty. | Rules for the command: * `--cmd` must include `$RESULT`. * The command runs directly, not through a shell. Pipes (`|`), redirects (`>`), and environment variables do not work. If you need them, put the steps in a script, and set the script as the command. * Put double quotes around a program path that has spaces. * On Mac and Linux, put the whole `--cmd` value in single quotes. Otherwise your shell replaces `$ANCESTOR` and the other placeholders before Diversion sees them. The temporary files keep the original file extension, for example `local.prefab`. This matters for tools that choose how to merge from the extension, such as UnityYAMLMerge and mergiraf. ### File patterns `--pattern` is a regular expression. Diversion matches it against the file path in the repository. | Pattern | Matches | | - | - | | `\.prefab$` | Files that end with `.prefab` | | `\.(unity\|prefab)$` | Files that end with `.unity` or `.prefab` | | `Characters/.*\.prefab$` | `.prefab` files inside any `Characters` folder | | `.*` | Every file | If more than one tool matches a file, **the first tool in the list wins**. `dv merge-tool add` puts a new tool at the end of the list. Use `dv merge-tool` to see the order. In the desktop app, drag the rows in **Settings > Merge tools** to change it. A file that matches no tool is left for you to resolve in the Diversion app. ### Exit codes and visual tools By default, the exit code of the tool decides the result, the same way as `git mergetool`: | Exit code | Result | | - | - | | `0` | Resolved. Diversion saves the content of `$RESULT`. | | `1` to `127` | The tool left the conflict unresolved. You resolve it in the Diversion app. | | `128` or higher | The tool failed. | Some visual tools exit with `0` even when you close them without saving. For these tools, add `--no-trust-exit-code`. In the desktop app, set **Result check** to **Diversion checks the result**. Diversion then ignores the exit code and checks `$RESULT`: * If the tool wrote `$RESULT` and the file has no conflict markers (`<<<<<<<`), the conflict is resolved. * Otherwise, Diversion asks: `Was the merge successful? [y/n]`. * If there is no terminal to ask in, for example in a CI job, the conflict stays unresolved. ## Examples ### Unity Smart Merge (UnityYAMLMerge) UnityYAMLMerge comes with the Unity Editor. It merges Unity scenes, prefabs, and other YAML assets. It works only on assets saved as text, so set **Asset Serialization Mode** to `Force Text` first (see [Unity best practices](/unity/unity-best-practices#initial-setup)). Change `6000.0.23f1` to your Unity version: ```bash macOS theme={null} dv merge-tool add --name unity-yaml \ --pattern '\.(unity|prefab|asset|mat|anim|controller)$' \ --cmd '"/Applications/Unity/Hub/Editor/6000.0.23f1/Unity.app/Contents/Tools/UnityYAMLMerge" merge -p $ANCESTOR $INCOMING $CURRENT $RESULT' ``` ```bat Windows (Command Prompt) theme={null} dv merge-tool add --name unity-yaml --pattern "\.(unity|prefab|asset|mat|anim|controller)$" --cmd "\"C:\Program Files\Unity\Hub\Editor\6000.0.23f1\Editor\Data\Tools\UnityYAMLMerge.exe\" merge -p $ANCESTOR $INCOMING $CURRENT $RESULT" ``` > [!NOTE] > > UnityYAMLMerge takes the files in the order base, remote, local, merged. This is different from most other tools. > [!TIP] > > On Windows, run the example in Command Prompt. PowerShell passes quotes inside arguments differently in different versions, so the quoted program path can break. ### mergiraf (JSON, YAML, and code) [mergiraf](https://mergiraf.org) understands the syntax of many file types. It can merge two changes on the same line, such as two new keys in one JSON object. ```bash theme={null} dv merge-tool add --name mergiraf \ --pattern '\.(json|ya?ml|toml)$' \ --cmd 'mergiraf merge $ANCESTOR $CURRENT $INCOMING -o $RESULT' ``` ### KDiff3 KDiff3 merges what it can on its own. It opens a window only when a conflict is left for you. ```bash theme={null} dv merge-tool add --name kdiff3 \ --pattern '\.(ini|cfg)$' \ --cmd 'kdiff3 $ANCESTOR $CURRENT $INCOMING -o $RESULT --auto' ``` ### Meld Meld exits with `0` even when you close it without saving, so add `--no-trust-exit-code`: ```bash theme={null} dv merge-tool add --name meld \ --pattern '\.txt$' \ --cmd 'meld $CURRENT $ANCESTOR $INCOMING -o $RESULT' \ --no-trust-exit-code ``` ## Resolve conflicts with your merge tools ### From the CLI Add `--conflict_resolution merge-tool` to [`dv merge`](/cmd-ref/merge), [`dv update`](/cmd-ref/update), or [`dv revert`](/cmd-ref/revert): ```bash theme={null} dv merge feature/new-level --conflict_resolution merge-tool dv update --conflict_resolution merge-tool dv revert --conflict_resolution merge-tool ``` If you have no tools set up, the command stops before it starts the merge. The tools run one conflict at a time. The CLI then prints the result for each file: ```text theme={null} merge encountered conflicts, resolving with external merge tools Resolved 1 conflict(s) with external tools: - Assets/Prefabs/Player.prefab (unity-yaml) Skipped 1 conflict(s), left for manual resolution: - Assets/Textures/Hero.psd: no merge tool is configured for this file Not all conflicts were resolved. Please resolve the rest manually: https://app.diversion.dev/repo//merges/ ``` | Result | Meaning | What to do | | - | - | - | | **Resolved** | The tool merged the file. Diversion saved the result to the merge. | Nothing. | | **Skipped** | No tool matches the file, the tool left the conflict unresolved, or you answered `n`. | Open the printed link and resolve the file in the Diversion app. | | **Failed** | The tool did not start, it exited with code `128` or higher, or a file download or upload failed. | Check the tool with `dv merge-tool`, then resolve the file in the Diversion app. | Diversion completes the merge only when every conflict is resolved. If any conflict is skipped or failed, the merge stays open and the command exits with a non-zero exit code, so scripts can detect it. ### From the Diversion desktop app In the desktop app, you run a merge tool on one conflicting file at a time, from the merge screen. The app uses the tools that you set up with `dv merge-tool add` or in **Settings > Merge tools** (see [Set up a merge tool](#set-up-a-merge-tool)). > [!NOTE] > > Merge tools run on your computer, so this works only in the desktop app. In the browser, the merge screen does not show the merge tool button. **1. Open the merge screen** In the desktop app, open a merge that has conflicts. For example, start a merge, and when the app reports conflicts, click **View conflicts**. The merge screen lists the conflicting files. **2. Select a file** If one of your merge tools matches the file, the file header shows **Resolve with \**. If no tool matches, the button does not appear, and you resolve the file in the merge screen as usual. **3. Run the tool** Click **Resolve with \**. Diversion downloads the versions of the file and runs the tool. While the tool runs, the header shows **Waiting for \...** and a **Cancel** button. **4. Merge in the tool** Merge the file in the tool, save the result, and close the tool. When the tool resolves the conflict, the app marks the file as resolved and shows the merged result. **5. Complete the merge** Repeat for the other files. When every conflict is resolved, click **Complete merge**. Rules in the desktop app: * Only one tool runs at a time. While a tool is open for one file, the button for other files is turned off. * **Complete merge** waits until the tool finishes. * If you already made changes to the file in the merge screen, Diversion asks before the tool result replaces them. Click **Replace with \** to continue. * For a tool that does not trust its exit code (`--no-trust-exit-code`, or **Diversion checks the result**), when Diversion cannot tell if the merge worked, the app asks **Did the merge work?** Click **Yes, it merged** to save the result. Click **No** or close the dialog to leave the conflict unresolved. If you do not answer in 10 minutes, the answer is **No**. * If the tool leaves the conflict unresolved or fails, the header shows the reason and the button again. Run the tool again, or resolve the file in the merge screen. * To undo the tool result, click **Revert to conflict** in the file header. The button to run the tool appears again. * The merge screen reads your tools when it opens. If you add a tool while the merge screen is open, open the merge again to use it. ## Manage your merge tools ```bash theme={null} dv merge-tool # list your tools, in match order dv merge-tool add ... # add a tool, or update the tool with this name dv merge-tool -d # remove a tool ``` When you add a tool with a name that already exists, Diversion replaces it and keeps its place in the list. In the desktop app, you can do the same in **Settings > Merge tools**. See [Set up tools in the desktop app](#set-up-tools-in-the-desktop-app). Diversion saves your tools in `~/.diversion/merge_tools.json` (on Windows, `%USERPROFILE%\.diversion\merge_tools.json`). Use `dv merge-tool` or the settings page to change them instead of editing the file. See [`dv merge-tool`](/cmd-ref/merge-tool) for all options. ## Troubleshooting | Message | Cause and fix | | - | - | | `no merge tools configured` | You have no tools. Add one with `dv merge-tool add`, or in **Settings > Merge tools** in the desktop app. | | `no merge tool is configured for this file` | No pattern matches the file path. Check your patterns with `dv merge-tool`. | | `the tool exited with code N and left the conflict unresolved` | The tool could not merge the file on its own. Resolve it in the Diversion app. | | `the tool wrote an empty file while a side still had content` | The tool did not write its result to `$RESULT`. Check that the command writes to `$RESULT`, for example with `-o $RESULT`. | | `the two sides differ only in metadata` | The file content is the same, but something else changed, such as the file name. A merge tool cannot help. Resolve it in the Diversion app. | | `failed to run merge tool` | Diversion could not start the program. Use the full path to the program, in double quotes if it has spaces. | | A visual tool marks the file as resolved when you close it without saving | Add the tool again with `--no-trust-exit-code`, or set its **Result check** to **Diversion checks the result**. | | `The merge tools changed outside this page` | The tools changed while you edited them on the settings page, for example with `dv merge-tool`. Click **Cancel**, then make your changes again. | ## Related * [`dv merge-tool`](/cmd-ref/merge-tool) -- CLI reference for managing merge tools * [Conflicts](/concepts/conflicts) -- types of conflicts and how to resolve them * [Branching and merging](/core-concepts/branching-merging) * [Unity best practices](/unity/unity-best-practices) # Obliterate Source: https://docs.diversion.dev/advanced/obliterate Permanently delete file blobs from a repository to reclaim storage and remove sensitive content. `obliterate` permanently deletes the underlying blob storage for every version of files that match a path pattern, across all branches and commits. Unlike `dv rm`, which records a deletion in history but keeps the old versions reachable, obliterate removes the bytes themselves and rewrites references in history so the blobs cannot be retrieved. Use it when: * A very large file (game build, dataset, mistakenly committed binary) is consuming storage and is no longer needed in history. * A secret, credential, or other sensitive file was committed and must be expunged. > [!WARNING] > > Obliterate is **destructive and irreversible**. It deletes every version of the matching files, including the latest one, not only the old versions. There is no undo. Always run a preview first and read the plan carefully before executing. ## Requirements * You must be a [**repository admin**](/basic/access-levels#organization-level-access). * Obliterate is not supported on git-synced repositories. * Run `dv obliterate` from inside a workspace of the repo: its folder or any folder in it. The CLI works on the repo of the folder you are in. From any other folder, it stops with `Current directory is not a diversion repository`. ## How It Works 1. You supply one or more path globs (e.g. `'/assets/*.psd'`). 2. The server resolves every (path, version) match across the repo's history. 3. Each match is classified as either **deletable** (the underlying blob is only reachable through paths covered by your globs) or **not deleted** (the same blob content is reachable through some other path that you did not include). 4. On execute, the deletion runs asynchronously. You get back a `job_id` you can poll for progress. The "not deleted" partition matters because Diversion stores file contents by hash -- the same bytes shared across paths are stored once. If the same content also lives at another path you did not include, the storage stays. The preview tells you exactly which other paths are blocking deletion -- you can widen your glob set and re-run. ## Glob Syntax Patterns are **anchored to the repo root**. Always quote them so your shell does not expand the wildcards. The repo root is the top folder of your workspace, so do not put the workspace folder's name in the pattern. For a workspace folder named `MyGame`, the folder `MyGame/Content/Old` is `/Content/Old/...`, not `/MyGame/Content/Old/...`. This is the same from any folder inside the workspace. | Pattern | Matches | | - | - | | `/assets/*.psd` | `.psd` files directly under `/assets/`, root-anchored | | `/assets/.../*.psd` | `.psd` files anywhere under `/assets/` (recursive) | | `/.../secrets.env` | Any file named `secrets.env` anywhere in the repo | | `/build/large.bin` | One specific file | For "anywhere under this folder", `...` must be its own path step: write `/assets/.../*.psd`, not `/assets.../*.psd`. Patterns are **case-sensitive**. `/content` does not match a folder named `/Content`. Match the case exactly as it appears in the repo. > [!NOTE] > > **Windows**: quote patterns with double quotes (`"/assets/.../*.psd"`), not single quotes. On Windows the single quotes are sent as part of the text, so the pattern starts with `'` and is rejected. On macOS and Linux either quote style works. The preview returns a warning if a pattern is broadly unanchored (e.g. matches across the entire repo, or only at the root when you probably meant recursive). Redundant patterns -- ones already covered by another pattern in the same call -- are also flagged. ## Preview Always start with a preview. Nothing changes on the server. ```bash theme={null} dv obliterate preview '/assets/old_textures/*.psd' ``` The preview returns: * **Headline counts**: deletable versions / files, not-deleted versions / files, and any matches in shared (grouped) storage that obliterate cannot reach. * **Reclaim estimate**: total bytes that will be freed, deduplicated by content hash (the same blob at N paths counts once). * **Deletable paths**: per-path summary -- versions and total bytes -- sorted by largest reclaim first. * **Not deleted paths**: per-path summary plus `unblock_paths`: the other paths in the repo that still hold the same content. Add them to your glob set if you want the blob removed. * **Per-glob summary**: for each input glob, the files / versions / total bytes it matched on its own (before cross-glob deduplication). Only surfaced in JSON output, and in the human CLI's per-glob block when you pass more than one glob. * **Warnings**: surfaced when a glob is broadly unanchored or redundant. Pass multiple globs in one call to plan their combined obliteration: ```bash theme={null} dv obliterate preview '/assets/*.psd' '/builds/.../*.pak' ``` ### Human vs JSON output The human CLI shows the **top 20** deletable / not-deleted paths sorted by bytes desc, with a trailing line like `... and 980 more (use --json for the full list)` when the result was capped. The server returns the full byte-desc-sorted lists; only the display is capped. For the full machine-readable plan, pass `--json`: ```bash theme={null} dv obliterate preview --json '/assets/old_textures/*.psd' | jq '.deletable_paths | length' ``` `--json` emits a single JSON document on stdout with banners and warnings suppressed (warnings move into a `warning` string field on the document). ## Execute Once the preview matches what you intend to delete: ```bash theme={null} dv obliterate execute '/assets/old_textures/*.psd' ``` You will be prompted to type the repository name or ID to confirm. Pass `--yes` to skip the prompt (for scripting): ```bash theme={null} dv obliterate execute --yes '/assets/old_textures/*.psd' ``` Execute returns the same plan as preview plus a `job_id` and starts polling the job until it reaches a terminal state. The polling cap is **18 seconds** (status endpoint every 3 seconds); for shorter jobs you will see the run complete inline, and for longer jobs the CLI prints the `job_id` and exits, leaving you to follow up with `dv obliterate status`. Flags: * `--nowait` -- enqueue and exit immediately without polling. The CLI prints the `job_id` and you check progress yourself. * `--json` -- emit a single JSON document instead of the human banner. **Requires `--yes`** -- an interactive confirmation prompt would corrupt the JSON stream. Exit codes: | Code | Meaning | | - | - | | `0` | Polling reached a terminal state and the job completed without failures. | | `2` | Polling reached a terminal state and the job had one or more failed deletions. | | `101` | The 18s polling cap elapsed with the job still in progress. Distinguishes "gave up waiting" from "done" so scripts can branch on it; follow up with `dv obliterate status`. | > [!NOTE] > > `execute` returns as soon as the job is enqueued -- the actual deletion runs in the background, which is why you poll the status endpoint for progress. > [!NOTE] > > Concurrent commits to the same files during an obliterate run are an edge case. Avoid running obliterate while other users are actively committing to the targeted paths. ## Tracking a Job Each execute returns a `job_id` (e.g. `dv.obliterate.593d2b8a8dbf47559bcc73c8bcf54f41`). Check progress with: ```bash theme={null} dv obliterate status ``` The response carries an overall `status` plus per-row counts: ``` Obliterate job dv.obliterate.593d2b8a8dbf47559bcc73c8bcf54f41 Status: in_progress Counts: pending=18200 done=11800 failed=0 Started: 2026-06-18T08:39:01.147736+00:00 ``` ### Status values | Status | Meaning | | - | - | | `queued` | The worker has not started yet. | | `in_progress` | Worker is running. `pending` is dropping as batches complete; `done` and `failed` are growing. | | `succeeded` | Worker finished and all rows are `done`. | | `failed` | Worker finished but one or more rows are `failed`. The response includes the first 20 errors with the failing SHA and a truncated error message. | | `archived` | The job has aged out of the queue but its counts are still inspectable. | A 404 from the status endpoint means there is no obliterate job with that id in this repo. ## What Gets Touched * **History**: the obliterated file versions are removed from the repo's change log. * **Open merges**: any open merge whose conflict referenced an obliterated file is closed, since finalizing it would otherwise produce a commit with a dead reference. ## Limits * The preview/execute resolution call has a server-side time budget (60 seconds). If your glob matches too many files, the call is rejected with an error asking you to narrow the pattern. Split the work into more specific glob sets and run them sequentially. * Files stored in **shared (grouped) storage** -- small files packed together for efficiency -- cannot be individually obliterated. The preview reports them as a separate skipped count so you know how many were excluded. ## Related * [`dv obliterate`](/cmd-ref/obliterate) -- CLI reference * [Storage](/concepts/storage) -- how blobs are stored and shared * [Going back in time](/basic/going-back-in-time) -- non-destructive history navigation # Pre-Commit Hooks Source: https://docs.diversion.dev/advanced/pre-commit-hooks Run custom scripts before commits to validate changes, enforce standards, and automate checks. Pre-commit hooks let you run custom scripts that automatically validate your changes before each commit. If the script exits with a non-zero code, the commit is blocked - giving you a chance to fix issues before they reach the repository. ## Overview Hooks are executable scripts stored in a `.dvhooks/` directory at the root of your repository. Because they live inside the repository, they sync to all collaborators just like any other file. **Common use cases:** * Lint and syntax checks * Code formatting enforcement * Preventing commits of large or forbidden files * Custom project-specific validation **How it works:** * Before a commit, Diversion runs the `.dvhooks/pre-commit` script with the committed files as command-line arguments * Exit code `0` means the hook passed - the commit proceeds * Any non-zero exit code means the hook failed - the commit is blocked * The hook's stdout/stderr output is displayed to the user > [!NOTE] > > Pre-commit hooks are client-side only. They run when committing via the CLI or Desktop app. Commits made directly through the WebApp or API bypass hooks. ## Creating a Pre-Commit Hook **1. Create the hooks directory** Create a `.dvhooks` directory at the root of your repository: ```bash theme={null} mkdir .dvhooks ``` **2. Create the hook script** Create a `pre-commit` script inside `.dvhooks/`. The script can be written in any language, as long as it's executable. ```bash Mac/Linux (.dvhooks/pre-commit) theme={null} #!/bin/sh echo "Running pre-commit checks..." # Committed files are passed as arguments ($@) for file in "$@"; do if echo "$file" | grep -q '\.js$'; then if grep -q "console.log" "$file"; then echo "Error: Remove console.log from $file before committing." exit 1 fi fi done echo "All checks passed." exit 0 ``` ```bat Windows (.dvhooks/pre-commit.bat) theme={null} @echo off echo Running pre-commit checks... REM Committed files are passed as arguments (%*) for %%f in (%*) do ( echo Checking %%f ) echo All checks passed. exit /b 0 ``` ```powershell Windows (.dvhooks/pre-commit.ps1) theme={null} Write-Host "Running pre-commit checks..." # Committed files are passed as arguments ($args) foreach ($file in $args) { if ($file -match '\.js$') { if (Select-String -Path $file -Pattern "console.log" -Quiet) { Write-Host "Error: Remove console.log from $file before committing." exit 1 } } } Write-Host "All checks passed." exit 0 ``` On Mac/Linux, make the script executable: ```bash theme={null} chmod +x .dvhooks/pre-commit ``` **3. Commit the hook** Commit the `.dvhooks/` directory to share the hook with your collaborators: ```bash theme={null} dv commit .dvhooks -m "Add pre-commit hook" ``` Once committed, every collaborator on the branch will have the hook and it will run automatically before their commits. ## File Arguments The files being committed are passed to your hook script as **command-line arguments**. Your script can access them via `$@` (Mac/Linux) or `%*` (Windows). When the file list is too large for a single command invocation, Diversion automatically splits it into chunks and runs the hook multiple times in parallel. If any invocation fails, the commit is blocked. **Example - check committed files for large binaries:** ```bash Mac/Linux theme={null} #!/bin/sh # Reject files larger than 100MB MAX_SIZE=$((100 * 1024 * 1024)) for file in "$@"; do if [ -f "$file" ]; then size=$(stat -f%z "$file" 2>/dev/null || stat -c%s "$file" 2>/dev/null) if [ "$size" -gt "$MAX_SIZE" ]; then echo "Error: $file is too large ($(($size / 1024 / 1024))MB, limit 100MB)." exit 1 fi fi done exit 0 ``` ```bat Windows theme={null} @echo off REM Check committed files for %%f in (%*) do ( echo Checking: %%f ) exit /b 0 ``` ## Environment Variables Diversion also passes context to your hook script via environment variables: | Variable | Description | | - | - | | `DV_REPO_ROOT` | Absolute path to the workspace root | | `DV_COMMIT_MESSAGE` | The commit message | | `DV_BRANCH` | Current branch name | **Example - require a ticket number in the commit message:** ```bash Mac/Linux theme={null} #!/bin/sh # Require commit messages to contain a ticket reference (e.g., PROJ-123) if ! echo "$DV_COMMIT_MESSAGE" | grep -qE '[A-Z]+-[0-9]+'; then echo "Error: Commit message must include a ticket number (e.g., PROJ-123)." echo "Your message: $DV_COMMIT_MESSAGE" exit 1 fi exit 0 ``` ```bat Windows theme={null} @echo off REM Require commit messages to contain a ticket reference (e.g., PROJ-123) echo %DV_COMMIT_MESSAGE% | findstr /R "[A-Z]*-[0-9]*" >nul 2>&1 if %errorlevel% neq 0 ( echo Error: Commit message must include a ticket number (e.g., PROJ-123). echo Your message: %DV_COMMIT_MESSAGE% exit /b 1 ) exit /b 0 ``` ## Skipping Hooks Use the `--no-verify` flag to bypass pre-commit hooks for a single commit: ```bash theme={null} dv commit -a -m "quick fix" --no-verify ``` This is useful for urgent fixes when you need to commit without running validation. ## Behavior Details * **Run time**: Diversion does not stop a hook because it runs for a long time, so a hook can run a full test suite. The `dv` CLI and the desktop app wait up to 20 minutes for the commit, including the hook. To use a shorter limit, set it in your hook script. * **Working directory**: The hook runs with the workspace root as its working directory. * **Output limit**: Hook output is capped at 1 MB. Output beyond that limit is truncated. * **Output display**: Hook output is always shown to the user, whether the hook passes or fails. * **Platform detection**: * **Mac/Linux**: Diversion looks for an executable file named `pre-commit` in `.dvhooks/`. If the file exists but isn't executable, you'll see an error prompting you to run `chmod +x`. * **Windows**: Diversion looks for `pre-commit.bat`, `pre-commit.cmd`, or `pre-commit.ps1` in `.dvhooks/` (checked in that order). # Revision Limits Source: https://docs.diversion.dev/advanced/revision-limits Keep only the latest N versions of matching files and prune older ones to save storage. Diversion stores every version of every file forever. For large binary files that change often -- game builds, textures, audio -- this adds up fast. A 500 MB texture saved every week is about 26 GB of history each year. A **revision limit** tells Diversion to keep only the latest N versions of the files that match a pattern. Older versions are pruned in the background to free storage. Unlike [`obliterate`](/advanced/obliterate), which removes **every** version of a file, a revision limit keeps the file and its most recent versions -- only the excess older versions are removed. > [!NOTE] > > Revision limits are available on **Studio** and **Enterprise** plans. > [!NOTE] > > A "version" (also called a revision) is one committed state of a file. `--keep 3` means Diversion keeps the three most recent committed versions of each matching file and prunes anything older. > [!WARNING] > > Pruning permanently deletes older file versions and cannot be undone. It runs automatically after every commit with no prompt or confirmation. Review a repo's rules with `dv prune list` before you rely on them. ## Usage examples | File type | Typical keep | | - | - | | Compiled assets (`.uasset`, `.pak`) | Head only (`1`) | | Large textures (`.psd`, `.tga`, `.exr`) | Last `3`-`5` | | Audio / video (`.wav`, `.mp4`) | Last `2`-`3` | | Build output directories | Head only (`1`) | | Source code and config (`.cpp`, `.h`, `.ini`) | No limit | ## Requirements * You must be an [**organization admin**](/basic/access-levels#organization-level-access). * Revision limits are not supported on repositories synced with Git. ## How it works 1. An admin adds one or more rules. Each rule is a path pattern plus a keep count (see [`dv prune`](/cmd-ref/prune)). 2. After every commit, Diversion checks the files that commit touched against the rules and prunes versions beyond the keep count. 3. Pruning runs in the background. It does **not** slow down the commit, and the person committing sees no prompt or warning. Pruning is silent by design: the admin (or a Perforce import) sets the policy, and committers cannot override it. Review what a repo will prune with `dv prune list`. ### Keep counts * `--keep ` -- keep the latest `N` versions (`1` to `999`). `--keep 1` keeps the head version only. * `--keep all` -- keep every version (never prune). Use this to carve a path back out of a broader limit (partially negate); see [Rule order](#rule-order). ### Branch-safe counting "Keep N" is counted **per branch**, not per repository: * Every branch's head version is always kept. * A file's stored bytes are deleted only when **no** kept version on **any** branch still needs them. So a version shared across branches survives until the last branch that needs it prunes it. When in doubt, Diversion keeps a version longer rather than deleting one a branch still needs. ### What is never pruned * **Drafts and shelves.** Uncommitted work and shelved changes are always preserved. * **Every branch's head.** The latest version on each branch is always kept, even with `--keep 1`. ## Glob syntax Patterns are **anchored to the repo root**. Always quote them so your shell does not expand the wildcards. This is the same pattern grammar as [`obliterate`](/advanced/obliterate#glob-syntax). | Pattern | Matches | | - | - | | `/....pak` | All `.pak` files anywhere in the repo | | `/Builds/....pak` | All `.pak` files anywhere under `/Builds/` | | `/Assets/Textures/....exr` | All `.exr` files anywhere under `/Assets/Textures/` | | `/Builds/...` | Everything under `/Builds/` | | `/Assets/hero.psd` | One specific file | ## Rule order Rules are an **ordered list**. When more than one rule matches a path, the **last matching rule wins**. Adding a rule appends it to the end, so a later rule can override an earlier one. Use this to keep everything under a subtree while limiting a wider pattern: ```bash theme={null} # Keep 1 version of every .pak file... dv prune add "/....pak" --keep 1 # ...except release builds, which keep every version. dv prune add "/Releases/....pak" --keep all ``` `dv prune list` prints rules in this priority order. ## Managing rules Use [`dv prune`](/cmd-ref/prune) to list, add, edit, and remove rules: ```bash theme={null} dv prune list # show all rules, in priority order dv prune add "/....psd" --keep 5 # keep the latest 5 versions of every .psd dv prune set --keep 3 # change a rule's keep count dv prune remove # delete a rule ``` Adding a rule applies it to **future** commits. It does not prune versions that already exist beyond the new limit; those are pruned as later commits touch each file. ## Coming from Perforce This is the Diversion equivalent of Perforce's `+S` / `+Sn` file type modifier, which keeps only the last N revisions of a file. When you [import a Perforce depot](/coming_from_perforce#migration-options), your existing `+S` rules can be brought over as Diversion revision limits so retention carries across the migration. The import produces a review report of the translated rules for an admin to apply. **Contact the Diversion team** to run a Perforce import. > [!NOTE] > > Diversion guarantees branch-safe counting by design. Perforce's `+S` behavior across branches changed between server versions and is not consistent -- Diversion always keeps every branch's head and never deletes a version another branch still needs. ## Related * [`dv prune`](/cmd-ref/prune) -- CLI reference for managing rules * [Obliterate](/advanced/obliterate) -- permanently delete every version of a file * [Storage](/concepts/storage) -- how Diversion stores and shares file versions * [Coming from Perforce](/coming_from_perforce) -- migration guide # Selective Sync Source: https://docs.diversion.dev/advanced/selective-sync Only sync the files you need This one is for artists who don't want code, or for developers who aren't artistically inclined. ## What is Selective Sync? Selective Sync is a feature that allows you to choose which folders you want to sync locally. This will allow you to only have the files you need to work on, saving space on your computer. ## How to use Selective Sync Click the **⋯** icon (**Workspace sync settings**) to the right of the workspace selector. Its menu is titled **This workspace**. Then choose **Selective sync**. Or press **Ctrl+K** (**Cmd+K** on Mac) and choose **Selective Sync**. You can also choose the folders before a clone starts, see [Choose folders before cloning](#choose-folders-before-cloning). **1. Open your repo** From your local folder, run `dv view`. Or click the Diversion logo at the top left to open the dashboard, and click **View** on the repo's row in the **Remote Repositories** tab. **2. Open the workspace sync settings** Click the **⋯** icon (**Workspace sync settings**) to the right of the workspace selector. A menu titled **This workspace** opens. Choose **Selective sync** ("Choose which folders sync to this workspace"). **3. Choose the folders to sync** The **Choose folders to sync** dialog opens. Checked folders sync to this workspace, unchecked folders stay in the cloud. Use **Select all** to check or uncheck everything, and the search box to [find a folder by name](/basic/find-files). Hover the info icon next to the title for the full rules. Click **Save** to apply. ### Unsyncing a folder Uncheck the folder in **Choose folders to sync** and click **Save**. If the folder is already on disk, Diversion asks **Delete these folders from this workspace?** and lists the folders that will stop syncing. Click **Save and delete**. The folders are removed from your workspace and stay in the cloud. ### What about my uncommitted changes? You can't unsync a folder that has uncommitted changes. If you try, Diversion shows: > Cannot deselect paths as they contain uncommitted changes. Either commit or reset them before changing preferences. Commit or [undo](/basic/undo-pending-changes) the changes in that folder, then unsync it. ## Choose folders before cloning Cloning a repository through the desktop app downloads every folder by default. To download only the folders you need, choose them in the clone dialog before the clone starts. Nothing is downloaded for the folders you leave out. **1. Open the clone dialog** Click the Diversion logo at the top left to open the dashboard, then on the **Remote Repositories** tab click the **...** button at the right end of the repository's row, next to **View**, and choose **Clone repo**. The dialog has a **Folders to sync** row, set to **All folders**. **2. Choose the folders** Click **Choose...**. The same **Choose folders to sync** dialog opens, listing the folders of the repository's default branch. Uncheck the folders you do not need and click **Done**. **3. Clone** The row now shows how many folders you chose, for example **3 folders**. Choose **Create New Folder** or **Create from Existing Folder**, click **Browse...** to pick the location, and click **Clone**. The workspace is created with your selection, so the folders you left out are never downloaded. > [!NOTE] > > If you select an existing workspace in the clone dialog, the row shows that workspace's current selection, and you can change it before the clone. ## Loose files Selective sync works on folders, not on individual files. When you unsync a subfolder, its parent folder becomes partially synced: only the subfolders you keep checked are synced. Files that sit directly in that parent folder stop syncing too, even though they are not inside the folder you unchecked. For example, if a folder contains `Maps`, `Characters` and a file `notes.txt`, unsyncing `Maps` also unsyncs `notes.txt`. This still supports the main use-case of this feature: 1. Artists who don't want to sync code locally can ignore the root `Source` folder, or equivalent. 2. Developers who don't want to sync heavy assets can ignore the root `Content` folder, or equivalent. ## Per workspace The selective sync feature works on a per-workspace basis. This means that you can have different selective sync settings for different workspaces. This is useful if you have multiple projects in the same repo, or if you're working on different parts of the same project. # Submodules Source: https://docs.diversion.dev/advanced/submodules Mount another repo inside your repo, pinned to a commit A submodule mounts one Diversion repo at a folder path inside another repo, pinned to a specific commit. Use it to share an engine, a library, or an art pack across projects: each project decides which version it uses, and upgrades are an explicit, reviewable change. ## 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: ```bash theme={null} dv submodule add libs/engine # pin to the tip of the repo's default branch dv submodule add libs/engine --ref # pin a branch's current tip, a commit, or a tag ID ``` `` 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 ```bash theme={null} dv submodule status ``` ``` PATH REPO PINNED COMMIT STATE LOCAL CHANGES libs/engine engine dv.commit.42 synced 0 libs/tools tools dv.commit.7 pin_mismatch 2 ``` * `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). Run `dv 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: ``` Submodules with pending work: libs/engine (engine): not on its pinned commit, 1 uncommitted change ``` ## Get or repair the files ```bash theme={null} dv submodule update # every submodule dv submodule update libs/engine # only the mounts you name ``` `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 ` 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: ``` libs/tools: not updated: the submodule has local changes; commit or revert them first ``` The command exits with an error when any mount was skipped, so scripts notice. Naming a mount that cannot be updated, or a path that is not a submodule, is an error. ## Update submodules automatically Run this inside the parent workspace: ```bash theme={null} dv submodule auto-update on dv submodule auto-update off dv submodule auto-update # prints the current setting: on or off ``` When the setting is on, Diversion runs `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 update` apply: 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 status` as not on its pinned commit. Run `dv submodule update` after 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: ```bash theme={null} cd libs/engine dv checkout main # the child starts detached; a commit needs a branch # edit files dv commit -a -m "my change" cd ../.. dv submodule repin libs/engine ``` `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: ```bash theme={null} dv submodule repin libs/engine --ref main ``` Moving a pin never overwrites work: if the mount has uncommitted changes, the repin is refused until you commit or undo them. ## Remove a submodule ```bash theme={null} dv submodule rm libs/engine ``` Removes the pointer and the local files. Like `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 status` in `libs/engine` shows the child's changes. * Edits inside the mount never show up as parent changes; the parent repo stays clean. * The child workspace is named ` submodule @ ` 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. # Agent Quickstart Source: https://docs.diversion.dev/agent-quickstart Set up Diversion as the version control for your coding agent This page is written for **AI coding agents** (Claude Code, Cursor, Codex, or any tool that runs shell commands). It explains how to use Diversion as the version control for a repository with the `dv` CLI. Diversion is a cloud-native version control system — an alternative to Git and Perforce, built for large binary files with automatic sync. **Use Diversion when** your repo has large or binary files (game assets, models, datasets, build artifacts) that Git and Git LFS handle poorly, when you want commits to sync to teammates automatically (no push or pull), or when you're running multiple agents that each need an isolated copy of the repo. Setting up Diversion yourself with the desktop app? Start with the [Quickstart](/quickstart) instead. > [!NOTE] > > **Pointing an agent here?** The full machine-readable docs index lives at [`docs.diversion.dev/llms.txt`](https://docs.diversion.dev/llms.txt) (and [`/llms-full.txt`](https://docs.diversion.dev/llms-full.txt) for the complete text). Give your agent that URL together with this page. ## How Diversion differs from Git Diversion is not Git. Internalize these rules before running commands: * **Auto-sync — no `push` or `pull`.** Every commit replicates to the cloud and to teammates automatically. There is no `dv push` or `dv pull`. * **No staging area — no `git add`.** Diversion tracks every change in the working tree continuously. You commit files directly. * **One workspace = one working directory.** A *workspace* is a local copy of a single branch. To work on two branches at once, use two workspaces — see [Run agents in parallel](#run-agents-in-parallel). * **Always pass a subcommand.** Run `dv status`, `dv commit`, and so on. Running bare `dv` opens an interactive shell; avoid it in non-interactive or agent contexts. ## Install > [tab] macOS / Linux > > ```bash theme={null} > curl -sL https://get.diversion.dev/unix | bash ; export PATH="$HOME/.diversion/bin:$PATH" > ``` > > Add the `export PATH` line to your shell profile (`~/.bashrc` or `~/.zshrc`) to make it permanent. > [tab] Windows > > Download and run the [Windows installer](https://get.diversion.dev/win). Confirm the install: ```bash theme={null} dv version ``` ## Authenticate ```bash theme={null} dv login ``` This opens a browser to sign in. **A human runs this once** in the environment where the agent operates; the agent reuses the session afterward. > [!NOTE] > > **Headless or CI agents (no browser):** generate an API token (in the web app: avatar → **Organization settings** → **Integrations** in the settings sidebar, then **Generate a new API token**) and authenticate non-interactively with `dv authenticate ` — no browser needed. The [CI/CD guide](/ci-cd) has the full setup. The same token also works as a `Bearer` token against the [REST API](/api-reference/introduction). API access requires the [Pro plan or above](https://www.diversion.dev/pricing). ## Core commands ```bash theme={null} # Start tracking a new project in the current directory dv init # Get a working copy of an existing repository dv clone [path] # See what changed in the working tree dv status # Commit all current changes (replicates automatically — no push needed) dv commit -a -m "your message" # Create a new branch and switch to it dv branch -c # Switch to an existing branch, commit, or tag dv checkout # Merge another branch into the current one dv merge # View history dv log ``` Full reference: [CLI Reference](/cmd-ref/about-cmd). ## Git → Diversion command map | Git | Diversion (`dv`) | | - | - | | `git clone ` | `dv clone [path]` | | `git init` | `dv init` | | `git add ` | *(not needed — changes are tracked automatically)* | | `git status` | `dv status` | | `git commit -am "msg"` | `dv commit -a -m "msg"` | | `git push` / `git pull` | *(not needed — auto-sync)* | | `git checkout -b ` | `dv branch -c ` | | `git switch ` | `dv checkout ` | | `git merge ` | `dv merge ` | | `git log` | `dv log` | | `git worktree add ` | `dv clone --new-workspace --ref ` | ## Run agents in parallel To run agents in isolated workspaces — the Diversion equivalent of `git worktree` — clone the repository into a separate directory with its own workspace, **each on its own branch**. The workspaces are isolated on disk, and a dedicated branch per agent keeps their commits from interfering. (Agents that share a branch still auto-sync to it and can conflict — give each one its own branch.) ```bash theme={null} # Create an isolated workspace on a dedicated branch dv clone /tmp/-agent-1 --new-workspace --ref ``` The agent works inside `/tmp/-agent-1` and commits as usual — changes auto-sync to that branch. When the work is done, tear the workspace down: ```bash theme={null} dv workspace # list workspaces to find the one to remove (id starts with dv.ws.) dv unregister -f # run from inside /tmp/-agent-1 — detaches the local copy dv workspace delete -f rm -rf /tmp/-agent-1 ``` > [!NOTE] > > Today this clones the full repository, including binary assets. For asset-heavy repositories (e.g. Unreal projects) that is a large download per workspace. Code-only ("selective sync") cloning from the CLI is on the roadmap. ## Next steps > [card] [Capture your agent's reasoning](https://github.com/DiversionCompany/diversion-claude) > > The Diversion plugin for Claude Code links every commit to the conversation that produced it, so you can ask later *why* any change was made. Optional. > [card] [CLI Reference](/cmd-ref/about-cmd) > > Every `dv` command, flag, and argument. > [card] [API Reference](/api-reference/introduction) > > Automate Diversion over REST. > [card] [SlothBot](/slothbot) > > Diversion's built-in AI coding agent. # Access Levels Source: https://docs.diversion.dev/basic/access-levels Understanding the access levels used in granular permissions Diversion uses a hierarchical access level system to control what users can do in a repository. Each level includes all the permissions of the levels below it. ## Access Level Hierarchy ``` Admin > Write > Merge > Read ``` Each higher level includes all permissions from lower levels. For example, a user with Write access can also Merge and Read. ## What Each Level Can Do | Level | Description | Operations | | - | - | - | | **Read** | View only | Browse files, view commit history, see diffs, download files, review | | **Merge** | Accept incoming changes | Accept non-conflicting changes from others during merge operations | | **Write** | Modify files | Commit changes, resolve merge conflicts | | **Admin** | Full control | | ## Organization-Level Access If a repository belongs to an organization, **organization owners and admins are treated as Admin on every repository in that organization** -- even repositories they were never invited to as a collaborator. This applies to every admin-gated operation, not just managing collaborators: things like obliterating files, editing branch protection, granular permissions, webhooks, and auto-lock / auto-release settings are all available to organization owners and admins on any repo in the org. If their direct repository access is already higher (unusual, since Admin is the top level), it is left as is. See [Organization Management](/basic/organization-management) for how organization roles are assigned. ## Repository-Level vs Path-Level Access **Repository-level access** is set when you invite a collaborator. This determines the maximum access level the user can have in the repository. **Granular permissions access** uses [granular permissions](/basic/granular-permissions) to control access for specific files or folders. For example, you can give someone Write access to the repository but restrict them to Read-only on sensitive paths. > [!NOTE] > > Granular permissions only restrict access - they cannot grant higher access than the user's repository-level permission. Once any granular permission rule exists in the repository, users without matching rules are denied all access by default. ## Choosing the Right Level | Use Case | Recommended Level | | - | - | | External reviewers or auditors | Read | | Team members who receive updates but don't directly modify files | Merge | | Active team members who commit code | Write | | Team leads and repository owners | Admin | > [!TIP] > > Start with the minimum access level needed. You can always grant additional access later. # Branch Protection Source: https://docs.diversion.dev/basic/branch-protection Prevent direct commits to important branches and require changes to be merged in Branch protection lets you safeguard important branches—such as your main branch or release branches—by blocking direct commits. Once a branch is protected, changes can no longer be committed to it directly; they must be made on another branch and merged in. Branch protection is available to all users at no additional cost. ## What Protection Does When a branch is protected: * **Direct commits are blocked.** Users cannot commit changes straight to the protected branch. * **Changes must be merged in.** To update a protected branch, make your changes on a separate branch and merge that branch into the protected one. * **Admins can optionally bypass.** You can allow administrators—or a specific list of users—to commit directly, bypassing the protection. ## Adding a Protection Rule **1. Open Branch Protection settings** Click your **profile avatar** in the top navigation and select **Organization settings**. In the settings sidebar, select **Repositories**, then select **Branch protection** in the repository column. **2. Confirm the repository** Check the repository picker at the top of the repository column and make sure the correct repository is selected before continuing. **3. Open the form** Click **Add protection rule**. **4. Select the branch** Under **Add branch protection**, open the **Branch** dropdown and choose the branch you want to protect. **5. Configure bypass (optional)** Under **Merge restriction**, choose how changes reach the branch: * **Allow merges** — merges need no approval. * **Require approvals to merge** — a merge needs the number of review approvals you pick (1 to 5). The review author cannot approve or request changes on their own review. Tick **Count only approvals given on the latest commit** to ignore approvals given before the newest commit on the branch being merged. After new commits land, reviewers must approve again before the branch can merge. * **Block all merges** — only bypass users (and admins, if allowed) can merge. Then choose who, if anyone, is allowed to commit directly to the protected branch: * **Allow admins to bypass** — toggle this on to let repository administrators commit directly. When off, the helper text reads *"Admins cannot bypass protection."* * **Bypass restrictions (optional)** — use the **Select users…** dropdown to add specific users who can bypass protection and commit directly to this branch. Leave both options untouched to enforce protection for everyone, including admins. **6. Add protection** Click **Add protection**. The branch is now protected. ## Managing Existing Rules Each existing rule lists the protected branch, its bypass status (for example, *"No bypass allowed"*), its merge restriction (for example, *"Requires 2 approval(s) on the latest commit"*), and any **Allowed users** who can commit directly. Use the **pencil** icon to edit a rule or the **trash** icon to delete it. ### Removing a Protection Rule To stop protecting a branch, go back to **Branch protection** (profile avatar → **Organization settings** → **Repositories** → **Branch protection**) and make sure the correct repository is selected in the repository picker. Find the rule for that branch and click the **trash** icon to delete it. Direct commits to the branch are allowed again immediately. # Changing the past Source: https://docs.diversion.dev/basic/changing-the-past How to undo, cherry-pick, edit, or copy details from a previous commit ## Undoing a commit Committed something and wish you hadn't? You can undo it. Diversion creates changes that are the opposite of that commit, and you commit them like any other change. From the CLI, use [`dv revert`](/cmd-ref/revert). **1. Go to your repo history** Open the workspace of the repo where your changes are. Make sure that you have no pending changes. In the left navigation rail, click **Commits**. **2. Select the commit to undo** Hover over the commit, click the **…** icon at the right of its row, and select **Undo this commit…**. In the dialog, click **Undo changes**. You may need to resolve a merge conflict first, as described in the last step. **3. Admire your work** Your workspace now has pending changes that reverse the commit. For example, if the commit changed a line in a file, the file shows as modified with that line changed back. Commit these changes to finish the undo. **4. Resolve a merge conflict?** If a later commit also changed a file that the undone commit touched, you get a merge conflict. For example, undoing the commit that created a file would delete it, but if a later commit modified that file, the two changes conflict. Resolve the conflict, as described in [Conflicts](/concepts/conflicts#merge-conflicts), before you commit. ## Editing a commit message Made a typo in your commit message, or want to add more detail? You can edit the message of any commit you authored directly from the Commits view. > [!NOTE] > > Editing commit messages is only available for the commit author, and is not supported for repositories synced with Git. **1. Open the commit menu** In the Commits view, hover over the commit whose message you want to change, click the **…** icon at the right of its row, and select "Edit commit message". **2. Update the message** An "Edit commit message" dialog will appear, showing the commit ID for reference and a text area with the current message. Edit the message as you like, then click "Update" to save it. ## Cherry-picking a commit Cherry-picking lets you take a specific commit from the history and re-apply its changes into your current workspace. This is useful when you want to bring in a particular change without merging an entire branch. Your workspace must have no uncommitted changes before cherry-picking. Cherry-picking is not available for the initial commit of a repository. In the Desktop App: **1. Find the commit in Commits** Open the Commits view and find the commit you want to cherry-pick. **2. Open the cherry-pick dialog** Right-click the commit, or hover over it and click the **…** icon at the right of its row, and select **Cherry-pick into workspace…**. **3. Choose what to apply** The dialog lists the files the commit changed, all selected. To pick only part of the commit, uncheck the files or folders you don't want, then click "Cherry-pick". The selected changes are applied to your workspace without being committed. **4. Resolve conflicts if needed** If the cherry-picked changes conflict with your current workspace, you'll be taken to the merge conflict resolution view. See [merge conflicts](/basic/working-in-parallel#merge-conflicts) for details on resolving them. A renamed file is picked by its new path. Picking the new path also removes the old one. The same options are available from the CLI, where you name the files and folders to pick after the commit ID. See the [cherry-pick command](/cmd-ref/cherry-pick) for details. ## Copying commit details Need to reference a specific commit in a conversation or a script? You can quickly copy a commit's ID or message straight from the Commits view. **1. Copy commit ID** In the Commits view, hover over a commit, click the **…** icon at the right of its row, and select "Copy commit ID". The ID is copied to your clipboard right away -- you'll see a "Copied commit ID" notification confirming it. **2. Copy commit message** Similarly, you can select "Copy commit message" from the same menu to copy the full commit message text to your clipboard. # Delete your account Source: https://docs.diversion.dev/basic/delete-account Permanently delete your Diversion account You can delete your Diversion account yourself from the **Profile** page. Diversion will check whether your account is safe to delete, show you exactly what you'll lose, cancel any active subscription, and remove your data. > [!WARNING] > > Deleting your account is permanent. All repositories you own are deleted along with their history, branches, and workspaces. Any active subscription is cancelled. This cannot be undone. ## Switching login methods If your real goal is to switch sign-in methods (e.g., from email/password to Google), see the FAQ: [I can't log in with Google / I can't log in with my password](/faqs#i-can’t-log-in-with-google-/-i-can’t-log-in-with-my-password). Switching currently requires deleting your account and signing up again with the new method, so back up or transfer any owned repositories first. ## What gets deleted When your account is deleted, Diversion: * Permanently deletes every repository you own (including history, branches, workspaces, and stored files). * Cancels any active subscription tied to your account and removes you from Stripe. * Removes you from every organization and shared repository you collaborate on -- the resources themselves stay, but you lose access. * Disables your login credentials (email/password, Google, or GitHub). * Revokes any pending invitations sent from your account. Repositories owned by other people are unaffected; only your access is revoked. Your local files are **not** deleted. Workspace folders already on your computer stay on disk as plain files -- they simply stop syncing with Diversion. Delete them manually if you no longer want them (see [After deletion](#after-deletion)). ## Open the delete account dialog **1. Open your profile page** Click your avatar in the top navigation and select **Your profile**. **2. Scroll to the Danger zone** The **Danger zone** section is at the bottom of the Profile page. **3. Click 'Delete account'** This opens the deletion wizard. Diversion immediately checks whether your account can be deleted. ## Resolve blockers (if any) Some account states block deletion until you fix them. If Diversion finds a blocker, the dialog lists what to resolve -- you cannot proceed until each item is cleared. ### "Repositories you own in other organizations" You own one or more repositories outside the blocking organization that have other collaborators. The dialog links to the first few. If there are more, it says how many and links to your dashboard. For each repository, either: * [Delete the repository](/basic/repo-management#deleting-a-repository) (if it's no longer needed), or * Remove every other collaborator from the repository -- see [Manage project access](/basic/manage-project-access). ### "Your organization has other members and repositories" You own an organization that has both repositories **and** other members. Resolve it by clearing one side: either remove every repository from the organization, or remove every other member. To clear the repositories, for each one: * [Delete the repository](/basic/repo-management#deleting-a-repository) (if it's no longer needed), or * [Transfer the repository to another organization](/basic/organization-management#transferring-a-repository-to-another-organization). To clear members instead, remove every other member from the organization -- see [Organization management](/basic/organization-management#removing-users). For repositories in the organization that are owned by other users, ask the owner to delete or transfer them, or [contact support](mailto:support@diversion.dev). After resolving the blockers, close the dialog and open it again -- Diversion re-checks on each open. ## Review what you'll lose If your account has no blockers but you still own or belong to repositories or organizations, the dialog shows a **step 1 of 2** review screen listing everything affected by deletion: repositories and organizations you own (which will be deleted) and ones you're a member of (which you'll lose access to). Review the list carefully. Anything you want to keep, transfer, or back up should be handled before continuing: * Clone repositories you own to a local folder if you want to keep a copy of the files. * Use **Transfer ownership** to hand a repository to a collaborator instead of deleting it -- see [Transferring repository ownership](/basic/organization-management#transferring-repository-ownership). Click **Continue** when you're ready to proceed. ## Confirm and delete The final step asks you to pick a reason for leaving, optionally leave feedback, and type your email to confirm. **1. Fill in the form** Pick a reason and optionally add feedback (up to 255 characters; for longer notes, email [support@diversion.dev](mailto:support@diversion.dev)). **2. Type your email** Type the email address associated with your Diversion account exactly. The **Delete account** button stays disabled until the email matches. **3. Click 'Delete account'** Diversion deletes your repositories, cancels your subscription, removes your login, and signs you out. You're redirected to the sign-in page. ## After deletion * Logging in with the deleted email no longer works on the web or desktop apps. * Any local workspace folders on your machine remain on disk as plain files but no longer sync with Diversion. Delete them manually if you no longer need them. * The deleted email address can be used to register a new account later. The new account starts fresh; previously deleted data is not recoverable. # Draft Commits Source: https://docs.diversion.dev/basic/draft-commits Request feedback on your changes before committing them ## What are Draft Commits? Draft commits let you request feedback on your changes **before** they're committed to your active branch. You can create a review directly from your uncommitted workspace changes. This keeps your commit history clean while still getting the code review you need. ## Why Use Draft Commits? Draft commits are ideal when you: * **Work on a single branch** and want a simpler review workflow * **Want early feedback** on work-in-progress changes before finalizing them * **Keep your history clean** by only committing approved changes * **Experiment with ideas** and want team input before making them permanent Draft commits are optional. You can still use the regular commit workflow if you prefer to commit first and review later. ## Draft Commits vs Reviews Here's a quick comparison to help you choose the right workflow: | | Draft Commits | Reviews | | - | - | - | | **When to use** | Get feedback before committing | Get feedback on existing commits/branches | | **Starting point** | Uncommitted workspace changes | Committed changes in a branch | | **Commit history** | Changes only committed after approval | Changes already in branch history | | **Workflow** | Edit → Send to review → Approve → Commit | Commit → Create review → Approve → Merge | | **Best for** | Single-branch workflow, work-in-progress | Multi-branch workflow, feature branches | | **Commit history** | Only approved changes committed | May include intermediate/experimental commits | | **Flexibility** | Easy to discard or modify before committing | Requires reverting or amending commits | Both features create the same review experience with comments, approvals, and notifications. The main difference is **when** you commit your changes - before or after getting feedback. ## Creating a Draft Commit **Step-by-Step Instructions:** 1. **Make changes in your workspace** * Edit files as you normally would * Your changes remain uncommitted in your workspace 2. **Open your repository** * Open your repository in the Diversion web app * Your workspace's pending changes appear in the **Files** view 3. **Click the dropdown arrow next to "Commit..."** * The commit button has a dropdown arrow (▼) on the right side * Click the arrow to open the dropdown menu * Select **"Send to review\..."** 4. **Confirm the files to send** * A confirmation dialog shows the files that will be sent to review * Review the file list and click **"Send to review"** to proceed 5. **Fill in the review details** * **Title** (required): Brief description of your changes * Example: "Add user authentication endpoints" * **Description** (optional): Detailed explanation for reviewers * Explain what you changed and why * Mention any areas where you need specific feedback * **Reviewers** (optional): Select teammates who should review your changes * You can add reviewers now or later 6. **Click "Send to Review"** * A review is automatically created with your uncommitted changes * Your workspace is automatically cleared so you can immediately continue working on other changes (the changes are safely stored in the draft) * Assigned reviewers receive email notifications ## Managing Your Draft Commits ### Viewing Your Drafts 1. **Open the branch selector** * Open the branch selector (top-left, showing the current branch and commit), then click the **Drafts** tab. 2. **Find your drafts** * Your draft commits appear under the **Drafts** tab * Each draft shows its title and source branch 3. **Access draft actions** * Click the **...** (more options) menu next to a draft to see available actions: * **View Review**: Open the associated review to see feedback and comments * **Update**: Switch to the draft to continue working on it * **Close**: Discard the draft commit You can have multiple draft commits open simultaneously, allowing you to work on different changes and get feedback on each independently. ## Updating a Draft Commit If you need to make changes to your draft after creating it: **Step-by-Step Instructions:** 1. **Find your draft** * Open the branch selector and switch to the **Drafts** tab. Locate your draft in the list. 2. **Click "Update"** * Click the **...** (more options) menu next to your draft * Select **"Update"** from the menu * Confirm by clicking **"Switch to draft"** in the dialog * This switches your workspace to the draft branch and loads the draft changes * You can now continue editing 3. **Make additional changes** * Edit files to address reviewer feedback 4. **Update the draft** * Commit your changes * The review updates automatically with your new changes * Reviewers see the updated diff ## After Review Approval Once your reviewers have approved your draft: 1. **Review the feedback** * Read through all comments and approvals * Make sure all concerns are addressed 2. **Finalize your changes** * Switch back to the draft if needed to make final adjustments * Ensure everything is ready to commit 3. **Commit the changes** * The approved changes can now be committed to your branch * Your commit history stays clean with only reviewed, approved changes 4. **The draft closes automatically** * Once merged or committed, the draft status changes to closed ## Closing a Draft Commit If you decide you don't want to proceed with a draft: **Step-by-Step Instructions:** 1. **Find your draft** * Open the branch selector and switch to the **Drafts** tab. Locate your draft in the list. 2. **Click "Close"** * Click the **...** (more options) menu next to your draft * Select **"Close"** from the menu 3. **Confirm closing** * Click **"Close draft"** in the confirmation dialog * This action cannot be undone 4. **Draft is removed** * The draft is deleted from your active drafts list * If you were on the draft branch, you are switched back to the source branch * Changes are discarded ## Working with Draft Reviews ### Review Process Draft commits create reviews automatically, so the review process works the same: * **Reviewers can comment** on specific lines or files * **Reviewers can approve or request changes** * **You receive notifications** when reviewers respond * **Discussion happens in the review** just like regular reviews For detailed review instructions, see the [Reviews documentation](/basic/reviews). ### Notifications You'll receive email notifications for: * When reviewers comment on your draft * When reviewers approve or request changes * When the review is closed/merged # The .dvignore file Source: https://docs.diversion.dev/basic/dvignore Safely ignore files not needed in your repository The `.dvignore` file is used by Diversion to specify files and directories that should be ignored when tracking changes. This helps keep the repository clean by excluding unnecessary or automatically generated files, such as build artifacts, temporary files, and cached data. ### Purpose Using a `.dvignore` file ensures that only relevant files are committed to the repository. This helps: * Prevent clutter from unnecessary files. * Improve performance by avoiding tracking large or frequently changing temporary files. * Avoid committing sensitive or auto-generated files. While `.dvignore` decides what the repository **tracks and stores**, [Selective Sync](../advanced/selective-sync) controls which of those already‑tracked files your workspace actually downloads. ### File Structure The `.dvignore` file consists of patterns defining which files or directories to exclude. It typically follows these rules: * A line starting with `#` serves as a comment. Put a backslash `\` in front of the first hash for patterns that begin with a hash. * Don’t mix comments and patterns on the same line. **Mixing them will cause the pattern to not have any effect.** * Wildcard `*` matches any sequence of characters (but does **not** cross `/` boundaries, unlike `**`). * Directories ending with `/` ignore all contents inside. * Negations `(!)` explicitly include files that might otherwise be ignored. #### Advanced rule semantics * **Root‑anchored `/`** – a leading slash matches from the repository root; without it, the pattern can match anywhere. * **Double asterisk `**`** – matches across directory boundaries (e.g., `Assets/**/config.ini`). * **Negation and ignored folders** – a `!pattern` can't re‑include a file if one of its parent folders is ignored. Diversion (like Git) doesn't look inside an ignored folder. Re-include the folder first, then ignore the rest of its contents: ```text theme={null} Saved/* !Saved/UnrealBuildTool/ Saved/UnrealBuildTool/* !Saved/UnrealBuildTool/BuildConfiguration.xml ``` `Saved/UnrealBuildTool/BuildConfiguration.xml` -> tracked. Everything else under `Saved/` -> still ignored. With only `Saved/*` and `!Saved/UnrealBuildTool/BuildConfiguration.xml`, the file stays ignored, because `Saved/*` ignores the `Saved/UnrealBuildTool` folder. * **Nested `.dvignore` files** – rules in nested directories override rules from parent directories. > **Git compatibility**: Diversion implements the same pattern‑matching semantics as Git’s `.gitignore`—including support for nested ignore files—so a source tree copied from Git will behave identically out of the box. > [!NOTE] > > **IMPORTANT NOTE:** Diversion treats existing `.gitignore` files (both root and nested) similarly to `.dvignore` files, so when a Git repository is transferred into Diversion its original ignore rules are preserved. On a self-hosted install, `.gitignore` files are off by default: see [Turning off .gitignore files](#turning-off-gitignore-files).\ > > When both `.dvignore` and `.gitignore` exist in the same directory, their patterns are merged and **`.dvignore` takes precedence** (last-match-wins). This lets you override `.gitignore` rules without editing the `.gitignore` itself.\ > > In some cases, such as transferring the Unreal Engine source repository from Git, you may want to remove the existing `.gitignore` files > and replace them with a custom ignore file tailored to your needs. #### Turning off `.gitignore` files To ignore files by `.dvignore` rules only, set the environment variable `DV_DISABLE_GITIGNORE` to `1` for the Diversion agent. The agent then skips every `.gitignore` file, in every repository on that machine. * The agent reads the variable when it starts. After you set it, quit the agent (right-click the Diversion icon in the system tray and select *Quit*), open a new command line, and run `dv`. * Files that only a `.gitignore` rule ignored start to sync. Before you turn `.gitignore` files off, add `.dvignore` rules for the files you want to keep local. * On a self-hosted install, `.gitignore` files are off by default on every machine. An admin can turn them back on. #### Enabling the V1 matcher Ignore-file matching in Diversion is versioned. The default works well for most projects, and **V1** is an opt-in upgrade whose pattern matching follows Git's `.gitignore` rules even more closely — last-matching-rule-wins precedence, negations that re-include paths, root-anchored patterns, `**` across directory boundaries, and nested ignore files. To turn it on, add this directive as the **first non-empty line** of your repository-root `.dvignore`, before any patterns (leading blank lines are fine): ``` # dv-ignore-version: 1 ``` If the directive is missing or isn't on the first non-empty line, Diversion keeps using the default matcher. For game‑engine projects Diversion ships a default **.dvignore** tailored to each engine. The snippets below are high‑level illustrations; check the actual **.dvignore** generated in your repo for the authoritative rules. #### Unreal ``` # Unreal Engine build files Build/* # Saved game states and config files Saved/* # Compiled intermediate files Intermediate/* # Editor cache files DerivedDataCache/* ``` #### Unity ``` # Unity temp folder .utmp/ # Unity Library /[Ll]ibrary/ # Temporary files /[Tt]emp/ # Object files /[Oo]bj/ # Build directories /[Bb]uild/ /[Bb]uilds/ # Log files /[Ll]ogs/ # User-specific settings /[Uu]ser[Ss]ettings/ # Memory captures /[Mm]emoryCaptures/ # Recordings /[Rr]ecordings/ ``` For the complete Unity `.dvignore` with IDE files, Addressables, Visual Scripting, and more, see [Unity Best Practices](/unity/unity-best-practices). #### Godot ``` # Godot internal directory .godot/ # Import cache folder .import/ # Export settings export.cfg # Export presets export_presets.cfg # Auto-generated translation files *.translation ``` You can modify the `.dvignore` file based on your project needs. If you work with additional tools or frameworks, consider adding their cache or temporary directories to improve repository management. For example, if you use a custom build system, you might add: ``` /build_output/ /temp_build_files/ ``` ### Ignoring already committed files > [!NOTE] > > IMPORTANT NOTE: Files and directories that are already committed, will NOT be ignored by .dvignore. > > 1. If you wish to ignore a committed path, you need to first delete it and commit the deletion. If the content of that path can’t be auto-generated, you should back it up somewhere else and copy back after committing the deletion. > 2. Notify your collaborators to backup their copies before committing the deletion, because updating with that commit will delete their copies too. > 3. Example of auto-generated paths: build artifacts and intermediates, auto-generated code. > 4. Example of non-auto-generated paths: credentials files, local configuration files. > [!NOTE] > > An empty directory will NOT be ignored if there is a **negation** rule for one of its descendants. > > When a directory has a **negation** rule for one of its descendants, Diversion keeps that directory **tracked**, even if the descendant file doesn’t exist yet. > > ``` > Build/* > !Build/app.dll > ``` > > Because `!Build/app.dll` re-includes a possible future file, the `Build/` directory itself is tracked (and will show up empty until `app.dll` appears). > If you really want to ignore `Build/` altogether, remove the negation line (`!Build/app.dll`). # Find files Source: https://docs.diversion.dev/basic/find-files Search the file tree by name, with * as a wildcard The search box above the file tree finds files and folders by name. It is the same box in the workspace panel, on a commit or shelf page, and in the folder pickers: **Choose folders to sync**, **Move**, **Upload**, and **New folder**. ## Plain text Type part of a name. For example, `.dll` finds every file or folder whose name contains `.dll`, in any folder, including `core.dll.meta`. Upper and lower case do not matter. ## Patterns with `*` Add `*` to match a whole name instead of part of it. `*.dll` finds every file ending in `.dll`, wherever it is in the repository: Put a folder name in front to search only there. `Binaries/Win64/*.dll` finds the `.dll` files directly inside that folder: A pattern must match the end of the path, starting at a folder boundary. | Pattern | Finds | Does not find | | - | - | - | | `*.dll` | every file ending in `.dll`, in any folder | `core.dll.meta` | | `plugins/*.dll` | `.dll` files directly inside a folder named `plugins` | `myplugins/x.dll`, `plugins/sub/x.dll` | | `plugins/**/*.dll` | `.dll` files anywhere under a folder named `plugins` | | | `/assets/*` | items directly inside the top-level `assets` folder | `src/assets/x` | | `report*` | names that start with `report` | `myreport.txt` | | `*report*` | names that contain `report` | | The rules: * `*` stands for any characters within one name, including none. * `**` as a whole folder name stands for any number of folders, including none. * A leading `/` starts the pattern at the top of the repository. * Every other character stands for itself, including `?` and `.`. * Upper and lower case do not matter. Results show the matching files and the folders above them. In a workspace cloned to your computer, the search runs locally, so results are instant even on large projects. # Get an existing project Source: https://docs.diversion.dev/basic/get-existing-project Clone a repo and manage files in your workspace A team member has [set up Diversion](/basic/start-using-diversion) for your project and [invited you to join](/basic/manage-project-access), or maybe you want to get your own project that you created on another computer. Let's get you set up: **1. Find the repo on the Remote Repositories tab** Click the Diversion logo at the top left to open the dashboard, and open the **Remote Repositories** tab. In the desktop app the dashboard also has a **Local Workspaces** tab; the web app shows only **Remote Repositories**. Click the **...** button at the right end of the repo's row, next to **View**, and select **Clone repo**. **2. Choose a folder** In the **Clone repository** dialog, leave **Select a workspace** set to **Create new workspace**. Choose **Create New Folder** to create a folder named after the repo, or **Create from Existing Folder** to use a folder you already have. Click **Browse...** to pick the location, then click **Clone**. To download only some folders, see [Choose folders before cloning](/advanced/selective-sync#choose-folders-before-cloning). The project should start downloading right away. When it's done, you can open it and start working! ## File operations Diversion gives you quick access to common file operations right from the Files view. Right-click any file, or hover over its row and click the **...** button at the right end, to open the file menu. Depending on the file and where you are, it offers **Open with Default App**, **Show in Finder** (macOS) or **Show in File Explorer** (Windows), **Rename**, **Move**, **Reset** (changed files only, see [Undo pending changes](/basic/undo-pending-changes)), **History**, **Lock File** and **Delete**. **Lock File** appears only for files, and only when [hard locks](/hard-locks) are available on your plan. A file that is already locked shows **Unlock File** instead. When viewing a file, more actions are in the file title bar. ### Open with default app (Desktop only) Right-click a file in the Files view and select **Open with Default App** to open it with whatever application your OS associates with that file type. When viewing a file, you can also click **Open local copy**, the icon to the right of the download icon in the file title bar. > [!NOTE] > > This option is only available for locally cloned workspaces. Make sure the Diversion agent is running. You can also use this to open project files directly -- for example, opening a `.uproject` file will launch it in Unreal Engine. Keep in mind that you may need to have previously opened the project with the correct engine version for this to work as expected. ### Open in Explorer (Desktop only) Right-click a file in the Files view and select **Show in File Explorer** (Windows) or **Show in Finder** (macOS) to open the containing folder in your system file explorer. > [!NOTE] > > This option is only available for locally cloned workspaces. Make sure the Diversion agent is running. This is also useful for opening project files directly. For example, you can use **Show in File Explorer** or **Show in Finder** to navigate to your Unreal Engine `.uproject` file and open it from there. ### Rename a file **1. Right-click the file** In the Files view, right-click on the file you want to rename and select **Rename**. **2. Enter the new name** A dialog appears with the current file name pre-filled. Type the new name for your file. **3. Confirm the rename** Click **Rename** to apply the new name. > [!WARNING] > > Don't forget to include the file extension in the new name (e.g. `.txt`, `.cpp`, `.uasset`). Omitting it may cause the file to become unrecognized by your OS or game engine. > [!NOTE] > > File names cannot contain any of these characters: `< > : " / \ | ? *` The renamed file will appear in your pending changes in **green** with a **double arrow (>>)** icon, indicating a move/rename operation. For CLI usage, see the [mv command](/cmd-ref/mv). ### Move a file **1. Right-click the file** In the Files view, right-click on the file you want to move and select **Move**. **2. Pick the target folder** A directory picker dialog opens. Browse to the folder where you want to move the file. **3. Confirm the move** Click **Move** to move the file to the selected folder. The file keeps its original name. The moved file will appear in your pending changes in **green** with a **double arrow (>>)** icon, indicating a move/rename operation. For CLI usage, see the [mv command](/cmd-ref/mv). ### Delete a file **1. Right-click the file** In the Files view, right-click on the file you want to delete and select **Delete**. **2. Confirm deletion** You'll see a confirmation dialog asking "Are you sure you want to delete the file '\[file-path]'?" Click the red **Delete** button to confirm, or cancel if you changed your mind. The deleted file will appear in your pending changes in **red** with an **x** icon, indicating it has been deleted. For CLI usage, see the [rm command](/cmd-ref/rm). ### View file history **1. Right-click the file** In the Files view, right-click on the file and select **History**. **2. Browse the history** The file history page shows all commits that changed this file, including the operation type (added, modified, moved), commit message, author, and date for each change. Click on any commit to see the diff for that version. By default, a change that arrived through a merge shows only the merge commit. Check **Show squashed commits** to also see the original commits from the merged branch, with their own author, message, and diff. This works across chained merges: a commit merged from one branch into another, and from there into yours, shows up too. ### File history graph The **Graph** view shows the same history as a branch graph instead of a list: one lane per branch, so you can follow a file across forks and merges and see which branch each revision was made on. **1. Open the file history** Right-click a file in the Files view and select **History**. **2. Switch to the Graph tab** Click the **Graph** tab at the top of the file history view. ![File history Graph view showing one lane per branch](https://mintcdn.com/diversion-2/POGcKcJ4DsK-xNy7/images/file-ops-history-graph.png?fit=max\&auto=format\&n=POGcKcJ4DsK-xNy7\&q=85\&s=e2a54e9716d68bca28a5ba6cab642cd3) **3. Read the graph** Each lane is a branch, labeled with its name at the newest revision in that lane. Your default branch is always the top lane, and revisions run oldest to newest, left to right. Every dot is one revision of the file. The ring around it is color-coded by what that commit did to the file - added, modified, moved, or deleted - and a commit that merged another branch in is drawn with a double ring. A **solid** line joins consecutive revisions on the same branch. A **dashed** line crosses between lanes: it marks where a branch forked from, and where a revision arrived by merge. A **dotted arrow** marks a cherry-pick: it runs from the revision the content was picked from to the commit that holds the pick. A commit that picked from several sources gets one arrow per source, each in its own color, side by side in the order the picks were applied. **4. Open a revision** Click any dot to see that revision's commit details: commit ID, message, author, branch, and date. Click **View commit** to open the commit in full. A cherry-picked revision also lists each commit it was picked from on a **Cherry-picked from:** line, with its commit ID and branch. Click **View source commit** to open it. **5. Load older revisions** Pan left to move back through the history. Older revisions load as you reach the edge of the graph. > [!NOTE] > > The graph always includes the original commits from merged branches, so it has no **Show squashed commits** checkbox - that control applies to the list view only. ### Annotate (blame) The **Annotate** view shows who last modified each line of a file, along with the commit message and date. This is useful for understanding how a file evolved and who is responsible for specific changes. > [!NOTE] > > Annotate is only available for text files. Binary files are not supported. **1. Open the file history** Right-click a file in the Files view and select **History**. **2. Switch to the Annotate tab** Click the **Annotate** tab at the top of the file history view. **3. Browse line-by-line attribution** The left panel shows a color-coded dot, how long ago the change was made, the author name, and the commit message for each line range. The right panel shows the file contents with line numbers. **4. View commit details** Hover over any entry in the left panel to see full commit details: author avatar and name, date, full commit message, and commit ID. Click **View commit** to navigate to that commit. For CLI usage, see the [annotate command](/cmd-ref/annotate). ### Restore a previous version When viewing a file at a specific commit, you can send that version to your workspace. This replaces the current file contents with the selected version, and the change appears in your pending changes. **1. Navigate to the file at a specific commit** You can get there in two ways: * From the **file history**: right-click a file, select **History**, then click on the commit you want. * From the **branch history**: open a commit, then click on the file you want to restore. **2. Send to workspace** In the file title bar, click **Send this version to workspace**: a left-pointing arrow in a circle, the last icon after the file size. The restored file will appear in your pending changes as a modification. You can review the changes and commit when ready. For CLI usage, see the [restore command](/cmd-ref/restore). ### Download a file When you click on a file in the workspace or commit view, a download icon appears in the file title bar, after the file size. Click it (**Download file**) to download the file to your computer. # Going back in time Source: https://docs.diversion.dev/basic/going-back-in-time Reverting to or branching from a previous commit You've been working on your project for a while, and you realize that you made a mistake a few commits ago. Or maybe you want to start a new feature based on an older version of your project. No worries! You can go back in time to a previous commit. ## Reverting to a previous commit One way to go back in time is to revert to a previous commit. This will create changes in your workspace that undo all of the commits from the commit you've chosen to revert to up to the current commit. This does not create a new commit! **1. Make sure you have no pending changes** Since this action will automatically create changes in your workspace, it must be clean beforehand. Undo or commit any changes you have. **2. Revert the chosen commit** In the **Commits** view, hover over the commit you want to revert to, click the **…** icon at the right of its row, and select **Revert to this commit…**. **3. Review the changes and commit** You'll be taken to the **Files** view where you'll see the changes that will be made. ## Branching from a previous commit Another way to go back in time is to create a new branch from a previous commit. This will create a new branch with the commit you've chosen as the base. **1. Choose which commit you want as the base for your new branch** In the **Commits** view, hover over the commit you want to branch from, click the **…** icon at the right of its row, and select **Create branch from here**. **2. Create a branch** Follow the steps to create a new branch, as described in [Working in parallel](/basic/working-in-parallel#creating-a-new-branch). # Granular Permissions Source: https://docs.diversion.dev/basic/granular-permissions Control access to specific paths within your repository Granular permissions allow you to set fine-grained access control for specific files and folders within a repository. Instead of giving users full repository access, you can restrict what they can read, write, merge, or administrate at the path level. ## When to Use Granular Permissions Granular permissions are useful when you need to: * **Protect sensitive paths**: Prevent team members from modifying security-critical code, configuration files, or production assets * **Restrict by role**: Allow designers to only modify assets while developers work on code * **Isolate components**: Let teams work on specific parts of the repository without accessing others ## Access Levels Diversion uses four hierarchical access levels: | Level | Description | | - | - | | **Admin** | Full control | | **Write** | Can modify files | | **Merge** | Can participate in merge operations | | **Read** | Can view files only | Access levels are hierarchical: Admin includes all privileges of Write, which includes Merge, which includes Read. See [Access Levels](/basic/access-levels) for details on what each level can do. ## Permission Types Each rule uses one of four permission types that control how access is granted or denied: | Type | Behavior | | - | - | | **Allow (Hierarchical)** | Grants the specified level **and all lower levels**. Example: Allow (Hierarchical) + Write grants Write and Read access. | | **Allow (Exact)** | Grants **only the exact level** specified. Example: Allow (Exact) + Write grants Write but not Read. | | **Deny (All Above)** | Stops rule evaluation and denies all access levels (the level field is ignored). Any permissions already granted by higher-priority rules (lower in table) are kept. | | **Deny (Exact)** | Denies **only the exact level** specified. Example: Deny (Exact) + Write denies Write but allows Read. | > [!TIP] > > Use **Allow (Hierarchical)** for most cases since it grants natural permission inheritance. Use **Exact** types when you need to grant or deny a specific level without affecting others (e.g., deny Write but keep Read). ## Path Patterns Path patterns specify which files a rule applies to. Patterns always start with `/` representing the repository root. | Wildcard | Behavior | | - | - | | `*` | Matches within a single directory only | | `...` | Matches recursively across all subdirectories | Here are some common patterns: | Pattern | Matches | | - | - | | `/path/to/file.txt` | Exact file match | | `/path/...` | All files under `/path/` recursively | | `/path/....py` | All `.py` files under `/path/` recursively | | `/path/*` | All files directly in `/path/` (not subdirectories) | | `/path/prefix*` | Files in `/path/` starting with "prefix" | ## Rule Priority Rules are evaluated from the **bottom of the table to the top**. When multiple rules match, the **highest permission wins** - unless a Deny rule stops evaluation. > [!NOTE] > > Rules lower in the table have **higher priority**. Deny rules can override Allow rules above them. ### Example: Multiple Allow Rules | # | User | Path | Level | Type | | - | - | - | - | - | | 1 | alice | /src/... | Write | Allow (Hierarchical) | | 2 | alice | /src/secret/... | Read | Allow (Hierarchical) | When Alice accesses `/src/secret/config.json`: * Both rules match * The highest permission (Write) is granted * **Result: Alice can Write** to files in `/src/secret/` ### Example: Using Deny to Restrict Access | # | User | Path | Level | Type | | - | - | - | - | - | | 1 | alice | /src/... | Write | Allow (Hierarchical) | | 2 | alice | /src/secret/... | Write | Deny (All Above) | When Alice tries to access `/src/secret/config.json`: 1. Rule 2 matches first (bottom, highest priority) - stops evaluation and denies all access 2. Rule 1 is never evaluated 3. **Result: Alice has no access** to files in `/src/secret/` > [!WARNING] > > **Deny (All Above)** is a terminal rule. When it matches, evaluation stops immediately - no more rules above it are checked. Any permissions already granted by higher-priority rules (lower in the table) are kept. You can reorder rules in the UI by dragging them to change their priority. ## Assigning Permissions Permissions can be assigned to: * **Individual users** - Apply rules to specific team members * **Groups** - Apply rules to all members of a group (requires an organization; see [Groups](/basic/groups)). Prefer groups over individual users - it keeps permissions easier to maintain as your team grows. Each rule must target either a user or a group, not both. Create separate rules if you need to apply the same pattern to both. ## Setting Up Granular Permissions **1. Open your organization settings** Click your **profile avatar** in the top navigation and select **Organization settings**. **2. Go to Permission rules** Select **Repositories** in the sidebar, then select **Permission rules** in the repository column. **3. Choose a Repository** Use the repository picker at the top of the repository column to select the repository you want to configure. **4. Edit the Table** Click the pencil icon at the right end of the table header to start editing. If the repository has no rules yet, click **Add permission rule** instead. **5. Add Rules** Click **+** at the bottom left, below the table, and fill in the new row: * **User or Group**: Who this rule applies to * **Path Pattern**: Which files are affected * **Access Level**: Admin, Write, Merge, or Read * **Permission Type**: How to apply the access level **6. Edit Existing Rules** You can reorder rules by dragging the handle at the left of a row (rules at the bottom have higher priority), edit any field, or delete a rule with the trash icon at the end of its row. **7. Save changes** Click **Save changes** at the bottom right, then confirm. ## Evaluation Logic When a user tries to access a file: 1. Find all rules matching the file path for the user (including their groups) 2. Evaluate rules from bottom to top (highest priority first) 3. For each rule: * If **Deny (All Above)** matches the requested level: Stop evaluating (previously granted permissions are kept) * If **Deny (Exact)** matches exactly: Mark exact level as denied, continue evaluating * If **Allow (Hierarchical)** or **Allow (Exact)** matches: Mark as granted, continue 4. Final decision: The highest granted permission wins, unless a deny was recorded > [!NOTE] > > **Default behavior:** > > * If there are **no granular permission rules** in the repository, users get their repository-level permission. > * Once **any rule exists** for any user, users without matching rules are **denied all access**. Make sure to add rules for all users who need access. ## API Access You can manage granular permissions programmatically using the [Granular Permissions API](/api-reference/repository-granular-permissions/list-granular-permissions). # Groups Source: https://docs.diversion.dev/basic/groups Name a set of organization members, then invite them to repositories or use them in permission rules A group is a named set of organization members. You can use a group in two ways: * **Invite it to a repository.** Everyone in the group becomes a collaborator in one step. This copies the current members once. People you add to the group later do not get access. * **Use it in [granular permission rules](/basic/granular-permissions).** A rule always applies to the group's current members. When you add or remove someone, the rule changes for them too. Groups belong to an organization, so you can use them only with repositories in that organization. ## Who can do what | Action | Who | | - | - | | Create, edit, or delete a group | Organization owners and admins | | Add or remove members | Organization owners and admins | | See groups and their members | Owners and admins see all groups. Other members see only the groups they belong to, and cannot change them. | | Invite a group to a repository | Repository admins, for groups they can see | | Use a group in a permission rule | Anyone who can edit the repository's [permission rules](/basic/granular-permissions) | ## Opening the Groups page 1. Click your **profile avatar** in the top navigation and select **Organization settings**. 2. In the settings sidebar, select **Groups**. If you belong to more than one organization, first pick the organization in the organization selector at the top left of the global bar. The **Groups** page lists each group with its description and number of members. To see who is in a group, click the group's name. ## Creating a group 1. [Open the Groups page](#opening-the-groups-page) and click **Create group**. 2. Enter a name. You can also add a description and pick members under **Members (optional)**. Then click **Create**. * Each group name must be unique in the organization. * Creating a group does not add you to it. To include yourself, pick yourself under **Members (optional)**. * You can only add people who are already members of the organization. To add someone who is not a member yet, [invite them to the organization](/basic/organization-management#managing-an-organization) first. ## Adding members 1. [Open the Groups page](#opening-the-groups-page) and click the group's name. 2. Under **Select a member to add…**, pick the person. They are added right away. What changes for the new member: * Permission rules that target the group now apply to them. * They do **not** get access to repositories the group was invited to before. Invite them to those repositories, or [invite the group again](#giving-a-group-access-to-a-repository). ## Removing members 1. [Open the Groups page](#opening-the-groups-page) and click the group's name. 2. Click **Member** next to the person and select **Remove**. 3. Click **Remove** to confirm. What changes for the removed member: * Permission rules that target the group no longer apply to them. * They **keep** access to repositories the group was invited to. To remove that access, remove them from each repository's collaborators. See [Managing repository collaborators](/basic/organization-management#managing-repository-collaborators). ## Editing a group 1. [Open the Groups page](#opening-the-groups-page) and click the menu icon at the end of the group's row. 2. Select **Edit group**. 3. Change the name or description, then click **Save**. To change who is in the group, see [Adding members](#adding-members) and [Removing members](#removing-members). ## Deleting a group 1. [Open the Groups page](#opening-the-groups-page) and click the menu icon at the end of the group's row. 2. Select **Delete group**, then click **Delete** to confirm. You cannot undo this. What changes: * Nobody loses repository access. People the group added stay collaborators. * Permission rules that target the group stop working. They no longer grant or deny access, but they stay in the rules list until you delete them. If the group has rules, the confirmation dialog lists the repositories that have them. ## Giving a group access to a repository 1. Open the repository's collaborators dialog. See [Managing repository collaborators](/basic/organization-management#managing-repository-collaborators). 2. Type the group name in the **Email, user, or group…** field. 3. Choose an access level and click **Send invite**. Every current member of the group becomes a collaborator right away. They do not need to accept an invitation. > [!NOTE] > > Inviting a group is a one-time action. People you add to the group later do not get access to repositories the group was invited to before. Invite them to those repositories, or invite the group again. * If a member already has access to the repository at a lower level, inviting the group at a higher level raises their access to that level. It never lowers anyone's access. * If you remove someone from the repository and later invite the group again, they are added back. ## Using a group in permission rules When you add a [granular permission rule](/basic/granular-permissions), choose the group in the **User / Group** column (**Select user or group…**). Each rule targets either one user or one group. In the rules table, a group shows a people icon next to its name, and a user shows their avatar. A rule always applies to the group's current members. When you add someone to the group, the rule applies to them. When you remove someone, it stops applying to them. ## Limitations * A group cannot contain other groups. * Branch protection, reviewers, and notifications work with individual users, not groups. # Import from Git Source: https://docs.diversion.dev/basic/import-from-git How to get an existing repo from Git into Diversion Importing an existing repo from Git can get you quickly up and running with Diversion. On the **Enterprise** plan, you can also enable bi-directional sync between your Git repo and Diversion, so that changes made in either place are reflected in the other. This is a great way to take Diversion for a test drive with no commitment. > [tab] Web UI > > To import a repo using the Web UI, follow these steps: > > **1. Enable Diversion Sync** > > Go to the [Diversion Sync GitHub App page](https://github.com/apps/diversion-sync) and install the app. Before you start: > > * Install it on the GitHub account or organization that owns the repo, and give it access to that repo. > * Sign in to Diversion with the account you will import with. When GitHub sends you back to Diversion, the app is linked to the account that is signed in. The email address does not matter. > * Finish within 1 minute of installing. If you are not signed in yet, sign in first. After 1 minute the link fails. > * One Diversion account can link to a GitHub account or organization. If a teammate already linked it, you cannot import from it with your account. > > If the link fails, uninstall the app in your GitHub settings and install it again. After 3 failed attempts, your account cannot link the app. Contact us at [support@diversion.dev](mailto:support@diversion.dev). > > **2. Open the repo selector and choose 'Import Git repository'** > > Go to [your Dashboard](https://app.diversion.dev/dashboard), open the repo selector dropdown (top-left), and choose **Import Git repository** from its footer (alongside **Create new repository** and **Import from Perforce**). > > **3. You'll be prompted to choose your import options** > > In the **Import Git Repository** dialog, choose whether you want to import your entire repo and keep all of its history, or just the latest commit from a specific branch: > > * **Import only latest commit**, then **Default branch** or **Custom branch:** followed by the branch name. > > * **Import all branches with history**. This gives you the option to **Enable continuous bi-directional sync**. > > > [card] Note > > > > Bi-directional sync is available on the **Enterprise** plan. To turn it on, contact us at [support@diversion.dev](mailto:support@diversion.dev). > > **4. Enter the url for the repo you want to import** > > Type it in the field whose placeholder reads **Repository URL**. For a repo that isn't on GitHub, also select **I confirm this repository does not use Git LFS**, because Git LFS is supported only for GitHub repositories. > > **5. Click the 'Import' button** > > **6. Wait for the import to complete** > > This happens in the background, and depending on the size of your Git repo can take a few minutes. > You will receive an email when the import is complete. > [tab] CLI > > To import a repo using the CLI, follow these steps: > > **1. Enable Diversion Sync** > > Go to the [Diversion Sync GitHub App page](https://github.com/apps/diversion-sync) and install the app. Before you start: > > * Install it on the GitHub account or organization that owns the repo, and give it access to that repo. > * Sign in to Diversion with the account you will import with. When GitHub sends you back to Diversion, the app is linked to the account that is signed in. The email address does not matter. > * Finish within 1 minute of installing. If you are not signed in yet, sign in first. After 1 minute the link fails. > * One Diversion account can link to a GitHub account or organization. If a teammate already linked it, you cannot import from it with your account. > > If the link fails, uninstall the app in your GitHub settings and install it again. After 3 failed attempts, your account cannot link the app. Contact us at [support@diversion.dev](mailto:support@diversion.dev). > > **2. Open a CLI terminal** > > Open your terminal of choice. > > > [card] Using the Diversion Interactive Shell > > > > If you want an interactive shell with nicer UI, open your terminal of choice and run the `dv` command. > > It works the same as your regular terminal, and you can use any of the `dv` commands (`commit`, `init`, etc...) directly without prefacing them with `dv`. > > **3. Import** > > Run the following command: > > ```bash theme={null} > dv import [git_url] > ``` > > This will start importing your repo into Diversion with the default name - the same as the repo's name in Git. > > There are several optional arguments for the `import` command. You can always run `dv help import` to see them in the terminal. > > > [accordion] \[repo-name] > > > > Passing a repo name to the `import command` will save the repo to Diversion with that name, instead of the repo's name in Git. > > > > ```bash theme={null} > > dv import [git_url] [repo-name] > > ``` > > > [accordion] --with-sync > > > > Enables bi-directional sync between your new Diverson repo and your Git repo. This means that any change you make to one repo will be reflected in the other. > > > > This is useful for testing Diversion or for keeping any Git-based pipelines you have in place. > > > > ```bash theme={null} > > dv import [git_url] --with-sync > > ``` > > > > > [card] Note > > > > > > Bi-directional sync is available on the **Enterprise** plan. To turn it on, contact us at [support@diversion.dev](mailto:support@diversion.dev). > > > [accordion] --git-branch > > > > By default, Diversion will import the latest commit from the default branch of your Git repo. If you want to import the latest commit from a different branch, you can use the `--git-branch` flag. > > > > ```bash theme={null} > > dv import [git_url] --git-branch [branch-name] > > ``` > > > [accordion] --with-history > > > > By default, Diversion will only import the latest commit from the default branch of your Git repo. If you want to import the entire repo with all of its history, you can use the `--with-history` flag. > > > > ```bash theme={null} > > dv import [git_url] --with-history > > ``` > > **4. Wait for the import to complete** > > This happens in the background, and depending on the size of your Git repo can take a few minutes. > You will receive an email when the import is complete. # Import from Git LFS Source: https://docs.diversion.dev/basic/import-from-git-lfs How to get an existing repo that uses Git LFS into Diversion Importing an existing repo from Git with LFS configured is very similar to importing a regular Git repo, with a few small differences that will be explained below. ## Importing a Git LFS repo The basic steps to import a Git LFS repo are the same as importing a regular Git repo. See the [Import from Git](/basic/import-from-git) page for more information. ## Considerations for Git LFS When importing a Git LFS repo, there are a few things to keep in mind: ### Supported storage backend Diversion currently only supports Github as a storage backend for Git LFS. If your files are hosted on a different Git LFS storage backend, please [contact us](https://www.diversion.dev/contact-us), drop in our [Discord server](https://discord.com/invite/HDAGJvgkuT) or [email us](mailto:hi@diversion.dev). ### Export to Git LFS When bidirectional sync is turned on, all files will be pushed to your Git repo, including files that are configured to be stored in Git LFS. This means that if you have a large number of files in your Diversion repo, you might hit the storage limits of your Git repo provider. To avoid this, consider importing without bidirectional sync. ### Cost considerations for initial import When importing a Git LFS repo, the files in the LFS storage will be downloaded to your Diversion repo. This might be counted against your LFS bandwidth quota, depending on your Git LFS storage provider. ### Cost considerations for bidirectional sync If you choose to continuously sync your Diversion repo with your Git LFS repo, keep in mind that your Git storage costs might increase, as you add more files to your Diversion repo. Consult with your Git repo provider's pricing for cost estimation. To minimize costs, consider disabling bidirectional sync. ### Performance considerations for bidirectional sync There is a key difference between how Diversion works and how Git LFS works. Diversion continuously syncs your files to the cloud, while Git uploads files only when you push changes. This means that if you have a large number of files to commit in your Diversion repo, with bidirectional sync turned OFF the operation is usually instantaneous - the files are usually already in the cloud by the time you commit them. With bidirectional sync turned ON, the files will have to be pushed to your Git repo first, which might take a while. This is a server-to-server operation, so it might still be faster than pushing the files from your local machine, but it's something to keep in mind. # Import from Perforce Source: https://docs.diversion.dev/basic/import-from-perforce How to import a Perforce depot, with its history, into a new Diversion repository You can import a Perforce depot into a new Diversion repository, history included. The import runs on a machine you provide, called the **import host**, which needs network access to your Perforce server. Your Perforce password stays on the import host; Diversion never receives it. The Diversion app creates the repository and an API token and generates the configuration file the import host needs. A script on the import host then runs the import in Docker, checking in with Diversion every 5 minutes. ## Requirements for the import host * One of these: * **Linux or another Unix:** `bash`, `cron`, and Docker Engine 20.10 or newer with the Docker Compose plugin 2.17 or newer. Optional: `curl` and the AWS CLI. Without them, the script runs them from a container image instead. * **Windows 10 or 11** with WSL 2 (Windows Subsystem for Linux). An admin must set it up once. The setup steps install Docker inside WSL, so you don't need Docker Desktop. On a virtual machine, WSL 2 needs nested virtualization. * Network access to your Perforce server and to Diversion over HTTPS ## Set up the import in the Diversion app **1. Open the Perforce import page** Go to [your Dashboard](https://app.diversion.dev/dashboard) and choose **Import from Perforce**. If it isn't there, click **New repository** at the top right and choose **Import from P4**. You can also choose **Import from Perforce** from the footer of the repo selector dropdown at the top left (alongside **Create new repository** and **Import Git repository**). \[!NOTE] On self-hosted installs, these options open a request form instead, and the Diversion team runs the import for you. **2. Download the import script** Choose the tab for your import host's operating system, and download its script: * **Linux / Unix:** click **Download p4_import_bootstrap.sh**. * **Windows:** click **Download install_windows_task.ps1**. It sets up the import inside WSL and downloads the Linux script there for you. Your browser may warn before it saves the file, because it is a script. Choose **Keep**. The scripts are the same for every import, and you can download them from this page at any time. **3. Name the new repository** The repository name is filled in from the depot name; change it if you like. The repository must belong to an organization. If you don't have one yet, you can create it here. **4. Fill in the import settings** See [Import settings](#import-settings) below for what each field does. **5. Click 'Create repository and import files'** Diversion creates the repository, an API token, and your import configuration. **6. Download local.env** Click **Download local.env**. The file contains the API token, your repository ID and the setup steps for Linux, Unix and Windows. > [!WARNING] > > This API token is shown only once. Download `local.env` before you leave the page. If you leave without it, you can create a new token and file: see [Recover a lost local.env](#recover-a-lost-local-env). ### Import settings | Field | What it does | | - | - | | **Depot to import** | The whole depot, as `//depot/...`. No spaces, `#` or `@`. To import only some branches, use **Branches to import**. | | **Depot type** | **Stream depot** if branches are streams; **Local (classic) depot** if branches are defined by path. | | **Branch name depth** | Local depots only, and only when **Branches to import** is empty. Leave empty to find branches from the depot's branch specs. Otherwise, every folder this many levels below the depot root becomes a branch: with `1`, `//depot/main/...` is the branch `main`; with `2`, `//depot/dev/feature/...` is the branch `dev/feature`. Use `0` to import the whole depot as one branch. | | **Is there more than one mainline in the depot?** | A Diversion repository holds one mainline and its descendants. If the depot has several, answer **Yes** and name the one to import in **Mainline branch**. Each other mainline needs its own repository. | | **Branches to import** | Optional. Comma-separated branch names with no spaces, such as `main,dev`. All names must have the same depth. Leave empty to import all branches. | | **Path to exclude** | Optional. A depot path prefix, such as `//depot/builds/`. Files under it are not imported. | ## Protect local.env `local.env` holds an API token with **admin access to your Diversion account**. Treat it like a password: * Keep it only on the import host, readable only by the user that runs the import (`chmod 600 local.env`, as in the steps below). On Windows, the setup script copies the file into WSL, makes that copy readable only by root, and deletes the one in your Downloads folder. * Don't commit it to version control, share it in chat or email, or copy it to other machines. ## Run the import on the import host > [tab] Linux / Unix > > Run these steps as the user that will run the import — a user with access to Docker. Don't use `sudo`: it would install the schedule in root's crontab. > > **1. Put both files in one directory** > > Copy `p4_import_bootstrap.sh` and `local.env` into the same directory on the import host, for example `/opt/dv-p4-import`, and `cd` into it. > > **2. Make the script executable** > > ```bash theme={null} > chmod +x p4_import_bootstrap.sh > ``` > > **3. Fill in your Perforce settings** > > Open `local.env` and fill in the Perforce connection at the bottom of the file: > > ```bash theme={null} > P4PORT=perforce.example.com:1666 > P4USER=import-user > P4PASSWD=... > ``` > > Leave `API_DOMAIN`, `API_TOKEN` and `REPO_ID` as generated. > > **4. Protect local.env** > > ```bash theme={null} > chmod 600 local.env > ``` > > **5. Run the script once to check the setup** > > ```bash theme={null} > ./p4_import_bootstrap.sh > ``` > > A successful first run downloads your import configuration, pulls the Diversion import image and starts it. > The output includes a line like `Remote env changed -- recreating: ...`, and `docker ps` shows the import container running. > The first run can take a few minutes while images download. > > **6. Schedule the import** > > ```bash theme={null} > ./p4_import_bootstrap.sh --install-cron > ``` > > This adds a crontab entry that runs the script every 5 minutes from this directory and appends its output to `bootstrap.log`. > Each run restarts the import if it stopped and applies any change to its configuration. > [tab] Windows > > The import runs inside WSL 2, in a Linux distro with Docker Engine. Windows Task Scheduler takes the place of `cron`. > Don't use Docker Desktop for the import, even if it is installed: its containers stop when the user signs out. > > **1. Prepare Windows (an admin, once)** > > These steps need a Windows administrator. Everything after them runs as the account that will run the import, with no admin rights. > > 1. Give that account the **Log on as a batch job** right: open the **Start** menu, type `secpol.msc` and press Enter, then go to **Local Policies** > **User Rights Assignment**. Without this right, the import never runs. > 2. Install WSL, then reboot: > > ```powershell theme={null} > wsl --install --no-distribution > ``` > 3. Set the power plan so the machine never sleeps. A sleeping machine runs no import. > > **2. Create a Linux distro with Docker** > > As the import account, run this in PowerShell. On an ARM machine, replace `amd64` with `arm64` in the URL. > > ```powershell theme={null} > mkdir $env:USERPROFILE\wsl > curl.exe -fL -o $env:USERPROFILE\wsl\noble.tar.gz https://cloud-images.ubuntu.com/wsl/releases/24.04/current/ubuntu-noble-wsl-amd64-wsl.rootfs.tar.gz > wsl --import Ubuntu-24.04 $env:USERPROFILE\wsl\ubuntu $env:USERPROFILE\wsl\noble.tar.gz --version 2 > wsl -d Ubuntu-24.04 -u root -- sh -c "curl -fsSL https://get.docker.com | sh" > ``` > > **3. Fill in your Perforce settings** > > Open `local.env` from your Downloads folder in Notepad and fill in the Perforce connection at the bottom of the file: > > ```bash theme={null} > P4PORT=perforce.example.com:1666 > P4USER=import-user > P4PASSWD=... > ``` > > Leave `API_DOMAIN`, `API_TOKEN` and `REPO_ID` as generated, and save the file. > Keep `local.env` and `install_windows_task.ps1` in your Downloads folder. If your browser added `(1)` to a file name, as in `local (1).env`, an older copy is still there: delete the older copy, then remove the `(1)`. > > **4. Set up and schedule the import** > > Run the script from your Downloads folder, in PowerShell: > > ```powershell theme={null} > cd (New-Object -ComObject Shell.Application).NameSpace('shell:Downloads').Self.Path > powershell -ExecutionPolicy Bypass -File .\install_windows_task.ps1 > ``` > > The script: > > * Copies `local.env` into `/root/p4-import` inside the distro and downloads `p4_import_bootstrap.sh` there. > * Runs the import script once to check the setup. The first run can take a few minutes while images download. If the check fails, the script stops before it adds the scheduled tasks. > * Adds two scheduled tasks that run every 5 minutes, also when nobody is signed in: one keeps the distro running, the other runs the import script and appends its output to `bootstrap.log`. > * Deletes `local.env` from your Downloads folder, because it holds secrets. The import uses the copy in the distro. > > It asks for your Windows password: Task Scheduler needs it to run the tasks when nobody is signed in. > After a reboot, the import starts again within 5 minutes. > > **5. Check that the tasks run** > > Wait a minute, then run: > > ```powershell theme={null} > schtasks /query /tn "Diversion P4 import bootstrap" /v /fo list > ``` > > `Last Result` should be `0`. ## Change the Perforce settings The setup check does not test the Perforce connection. If the settings are wrong, the import stops, and `docker logs` shows a Perforce login error. > [tab] Linux / Unix > > Edit `local.env` in the import directory. The next run, within 5 minutes, applies the change. > [tab] Windows > > Edit the copy of `local.env` in the distro, in PowerShell: > > ```powershell theme={null} > wsl -d Ubuntu-24.04 -u root -- nano /root/p4-import/local.env > ``` > > Save with Ctrl+O and exit with Ctrl+X. The next run, within 5 minutes, applies the change. ## Follow the import's progress Open the new repository in Diversion. Until the import finishes, the repository page shows its progress through three stages: **Reading history**, **Preparing history** and **Uploading files**. Commits, branches and files appear once history is ready. Files open as soon as their contents are uploaded. Large depots take a long time to import. The import host must stay on and connected until it finishes. ## Stop or remove the import The schedule keeps the import running until you remove it. > [!NOTE] > > Keep the schedule if you need continuous import from Perforce, or export back to it, after the initial import. [Contact support](mailto:support@diversion.dev) to enable continuous import or export. When the import is done and you don't need it to continue: > [tab] Linux / Unix > > 1. Run `crontab -e` and delete the line containing `p4_import_bootstrap.sh`. > 2. Delete `local.env` from the import host. > [tab] Windows > > 1. Delete the scheduled tasks, in PowerShell: > > ```powershell theme={null} > schtasks /delete /tn "Diversion P4 import bootstrap" /f > schtasks /delete /tn "Diversion P4 import keep-alive" /f > ``` > 2. Remove the distro, with everything in it, including `local.env`: > > ```powershell theme={null} > wsl --unregister Ubuntu-24.04 > ``` ## Troubleshooting The script writes errors to its output and, once scheduled, to `bootstrap.log` in the import directory. On Windows, run the commands below inside the distro: put `wsl -d Ubuntu-24.04 -u root --cd /root/p4-import --` in front of them, for example `wsl -d Ubuntu-24.04 -u root --cd /root/p4-import -- tail -n 50 bootstrap.log`. | Message or symptom | What to do | | - | - | | `Local config not found at ./local.env` | Run the script from the directory that holds `local.env`. | | `Missing required variable in ./local.env: ...` | Fill in the named value in `local.env`. | | `API_TOKEN must be an API token from the account page (starts with dvk_)` | `API_TOKEN` was changed or truncated. Restore the generated value. | | `docker compose >= 2.17 required` | Upgrade to Docker Engine 20.10+ with the Docker Compose plugin 2.17+. | | `crontab already has a p4_import_bootstrap.sh entry` | The import is already scheduled. To move it to another directory, delete the old entry with `crontab -e` first. | | `... returned HTTP 401` | The API token was revoked or is invalid. The import stops until you fix it. [Generate a new token](/ci-cd#generate-an-api-token) and replace `API_TOKEN` in `local.env`. | | `... returned HTTP 403` | The token's user no longer has admin access to the repository. The import stops until that's restored. | | `... returned HTTP 404` | Check that `REPO_ID` in `local.env` matches the repository. If it does, contact support. | | `... did not include an ETag` | Something on your network, such as a proxy, strips response headers. Check your proxy settings, or contact support. | | `Another bootstrap run is in progress -- skipping this tick` | Normal now and then, such as while the first run downloads images. If it repeats for hours, check `bootstrap.log` for a stuck run. | | The import page says **This repository already has an import configuration** | The settings for this repository can't be changed from the page. Contact support to change them. | | The repository page stays on **Waiting for the import to start** | Check that the schedule exists and that `bootstrap.log` shows no errors. On Linux and Unix, run `crontab -l`. On Windows, see [Check that the tasks run](#run-the-import-on-the-import-host). | | **No progress in 30 min** | Large depots can pause here. If it continues, check that the import host is running and the import container is up (`docker ps`). | | **Import stopped** | Check that the import host is running and look at the container's output with `docker logs`. If the import doesn't resume, [send the logs to Diversion support](#send-logs-to-diversion-support). | | `docker logs` shows a Perforce login or password error | [Change the Perforce settings](#change-the-perforce-settings). | ### Troubleshooting on Windows | Message or symptom | What to do | | - | - | | `Fill in P4PORT, P4USER, P4PASSWD in ...local.env` | Fill in the named values in `local.env` in Notepad, save the file and run the setup command again. | | `... has local (1).env. Delete the older copies, rename the newest one to local.env, ...` | Your browser renamed a new download. Delete the older copies, rename the newest one to `local.env`, and run the setup command again. | | `The setup check failed` | The import script's error is printed above this message. Find it in the table above, fix it and run the setup command again. `local.env` stays in your Downloads folder until the setup succeeds. | | A task's `Last Result` is `267011` | The task never ran: the account lacks the **Log on as a batch job** right. Ask an admin to grant it, then run the setup command again. | | The import stopped after you changed your Windows password | The tasks still use the old password. Run the setup command again and enter the new one. | | The Perforce server runs on the same Windows machine and the import can't reach it | Inside a container, `localhost` is the container itself. Use the machine's IP address in `P4PORT`. | ### Send logs to Diversion support If the import fails or stops and you can't find the cause, send its logs to Diversion support. Run this in the import directory: ```bash theme={null} ./p4_import_bootstrap.sh --support "short description of the problem" ``` On Windows, run this in PowerShell instead: ```powershell theme={null} wsl -d Ubuntu-24.04 -u root --cd /root/p4-import -- bash p4_import_bootstrap.sh --support "short description of the problem" ``` The running import is not stopped. Make sure `API_TOKEN` is set in `local.env`, because it is used for authentication when uploading. If it is missing, the upload fails; see [If the upload fails](#if-the-upload-fails). When the upload succeeds, the output says `Support bundle sent to Diversion`, and our support team gets your description. The uploaded file contains: * The import logs from the last 3 days. Long logs are shortened: the start, the end and every warning and error are kept. * The recent output of the import containers and the end of `bootstrap.log`. * The settings in `local.env` and in the import configuration. Values of secret settings, such as `P4PASSWD` and `API_TOKEN`, are replaced by their length. * Basic details of the import host: operating system, free disk space and Docker version. #### If the upload fails A copy of the file stays at `dv-bootstrap/p4-support-bundle-