External Merge Tools

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.

Install the merge tool on your computer

For example, install mergiraf to merge JSON files. For Unity and other tools, see Examples.

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.
- Name: mergiraf
- File pattern: \.json$
- Command: mergiraf merge $ANCESTOR $CURRENT $INCOMING -o $RESULT

CLI: run dv merge-tool add:

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.

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:

dv merge <branch> --conflict_resolution merge-tool

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 <tool>. You run the tool one file at a time. See 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.

How it works

You start a merge, update, or revert.
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.
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 <tool>. With the CLI, it happens for every conflict.
When every conflict is resolved, you complete the merge. In the desktop app, click Complete merge. The CLI completes the merge for you.
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.

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

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.

Add the tool to Diversion

Tell Diversion which files the tool handles and how to run it:

dv merge-tool add --name <name> --pattern '<regex>' --cmd '<command>'

See Examples for ready-to-use commands.

Check your setup

List your tools, in the order Diversion matches them:

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.

The Merge tools settings page in edit mode, with four tools: unity-yaml, mergiraf, kdiff3, and meld — Settings > Merge tools while you edit, with the tools from Examples

Start editing

Click the edit (pencil) button in the table header. If you have no tools yet, click Add merge tool.

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.
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.

Set the order

Drag the rows to change the order. Diversion checks the tool with Priority 1 first.

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, 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). Change 6000.0.23f1 to your Unity version:

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'

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"

UnityYAMLMerge takes the files in the order base, remote, local, merged. This is different from most other tools.

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 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.

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.

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:

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, dv update, or dv revert:

dv merge feature/new-level --conflict_resolution merge-tool
dv update --conflict_resolution merge-tool
dv revert <commit_id> --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:

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/<repo_id>/merges/<merge_id>

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 merge screen with Config/DefaultGame.ini open and a Resolve with kdiff3 button in the file header — The kdiff3 tool matches the open file, so the file header shows Resolve with kdiff3

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).

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.

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.

Select a file

If one of your merge tools matches the file, the file header shows Resolve with <tool>. If no tool matches, the button does not appear, and you resolve the file in the merge screen as usual.

Run the tool

Click Resolve with <tool>. Diversion downloads the versions of the file and runs the tool. While the tool runs, the header shows Waiting for <tool>… and a Cancel button.

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.

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 <tool> 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

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 <name>  # 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. 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 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.

dv merge-tool — CLI reference for managing merge tools
Conflicts — types of conflicts and how to resolve them
Branching and merging
Unity best practices

Get Started

AI

Collaborate

Work with Unreal Engine

Work with Unity

Integrations

Reference

CLI Reference

Changelog

Quick start

How it works

Set up a merge tool

Set up tools in the desktop app

Command placeholders

File patterns

Exit codes and visual tools

Examples

Unity Smart Merge (UnityYAMLMerge)

mergiraf (JSON, YAML, and code)

KDiff3

Meld

Resolve conflicts with your merge tools

From the CLI

From the Diversion desktop app

Manage your merge tools

Troubleshooting

​Quick start

​How it works

​Set up a merge tool

​Set up tools in the desktop app

​Command placeholders

​File patterns

​Exit codes and visual tools

​Examples

​Unity Smart Merge (UnityYAMLMerge)

​mergiraf (JSON, YAML, and code)

​KDiff3

​Meld

​Resolve conflicts with your merge tools

​From the CLI

​From the Diversion desktop app

​Manage your merge tools

​Troubleshooting

​Related

Quick start

How it works

Set up a merge tool

Set up tools in the desktop app

Command placeholders

File patterns

Exit codes and visual tools

Examples

Unity Smart Merge (UnityYAMLMerge)

mergiraf (JSON, YAML, and code)

KDiff3

Meld

Resolve conflicts with your merge tools

From the CLI

From the Diversion desktop app

Manage your merge tools

Troubleshooting

Related