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

Add a merge tool, once per computer. This one merges JSON files:

dv merge-tool add --name mergiraf --pattern '\.json$' --cmd 'mergiraf merge $ANCESTOR $CURRENT $INCOMING -o $RESULT'

Merge with your tools:

dv merge <branch> --conflict_resolution merge-tool

Diversion merges what it can on the server. For each conflict that is left, it runs the tool that matches the file. If a conflict is still open at the end, finish it in the Diversion app.

For Unity and other tools, see Examples.

How it works

You start a merge, update, or revert with the merge-tool conflict resolution.
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.
If the tools resolve every conflict, Diversion completes the merge and creates the commit.
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

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

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. Diversion saves your tools in ~/.diversion/merge_tools.json (on Windows, %USERPROFILE%\.diversion\merge_tools.json). Use dv merge-tool 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`.
`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`.

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

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

Manage your merge tools

Troubleshooting

​Quick start

​How it works

​Set up a merge tool

​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

​Manage your merge tools

​Troubleshooting

​Related

Quick start

How it works

Set up a merge tool

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

Manage your merge tools

Troubleshooting

Related