Smart merge

Use the UnityYAMLMerge tool to merge scene and prefab files in a semantically correct way.

Read time 10 minutes

Last updated a day ago

Use the UnityYAMLMerge tool to merge scene and prefab files in a semantically correct way. You can run the tool from the command line, and several version control tools integrate it directly.

Merging capabilities

UnityYAMLMerge merges scene (

.unity

), prefab (

.prefab

), and

.meta

files. For other files, and for conflicts it can't resolve, it uses fallback merge tools listed in the

mergespecfile.txt

file. These fallbacks let you use UnityYAMLMerge as the main merge tool for version control systems that don't select merge tools based on file extension. The spec file already lists the most common merge tools, and you can edit it to add tools or change options. For the location of this file, refer to Configuration file locations.

By default, UnityYAMLMerge doesn't merge other YAML-serialized files, such as

.asset

.mat

, or

.controller

files. If your version control tool passes these files to UnityYAMLMerge, UnityYAMLMerge hands them to a fallback merge tool. To merge them with UnityYAMLMerge anyway, use the

--force

argument. For more information, refer to UnityYAMLMerge command-line reference.

When to use smart merge

Smart merge is useful when two people change the same scene or prefab file in parallel, and your version control system needs to combine the changes. This happens when you work on separate branches, or when your version control system doesn't lock files on checkout.

If your team uses exclusive checkout to lock scene and prefab files, two people can't edit the same file at the same time, and you don't need smart merge for those files.

In most workflows, you don't run UnityYAMLMerge yourself. After you set it up, your version control tool runs it when you resolve a merge conflict in a scene or prefab file. For example, Unity runs it when you resolve conflicts in the Editor with Perforce, and Git runs it when you run

git mergetool

. You can also run UnityYAMLMerge from the command line. For more information, refer to UnityYAMLMerge command-line reference.

Set up smart merging in Unity

How you set up smart merging in the Editor depends on the version control system configured in Edit >

Project Settings

Version Control

Unity Version Control

When Mode is set to Unity Version Control, the Unity Version Control client resolves merges, not Unity. The client uses the merge tools set in its own preferences.

The Revision Control Diff/Merge preference in Unity doesn't control how the Unity Version Control client merges files. For example, selecting PlasticSCM Merge there doesn't make the client use UnityYAMLMerge.

To use UnityYAMLMerge for scene and prefab files, add it as a merge tool in the Unity Version Control client. For more information, refer to Set up for Unity Version Control.

Perforce

When you use Perforce, Unity can use UnityYAMLMerge when you resolve conflicts in scene (

.unity

) and prefab (

.prefab

) files from inside the Editor.

To set up smart merging:

Go to Edit > Project Settings > Version Control.
In Mode, select
Perforce
?
.
In Smart merge, select one of the following options:
- Off: Don't use smart merging. Unity uses only the merge tool set in Edit > Preferences > External Tools > Revision Control Diff/Merge (macOS: Unity > Settings > External Tools > Revision Control Diff/Merge).
- Premerge: Smart merge the file first. If the result has no conflicts, Unity uses it. If conflicts remain, Unity opens the external merge tool with premerged versions of the base file, your version, and the other version, so that you only see the remaining conflicts.
- Ask: Each time you merge a scene or prefab file, Unity asks you which method to use: Semantic and merge tool (same as Premerge) or Merge tool only (same as Off). This is the default.

Set up UnityYAMLMerge in your tools

To set up UnityYAMLMerge:

Locate UnityYAMLMerge.
Follow the instructions for your tool.

Locate UnityYAMLMerge

The UnityYAMLMerge tool is included with the Unity Editor.

When Unity is installed in the default Unity Hub location, the path to UnityYAMLMerge is:

On Windows:


C:\Program Files\Unity\Hub\Editor\<version>\Editor\Data\Tools\UnityYAMLMerge.exe

On macOS:


/Applications/Unity/Hub/Editor/<version>/Unity.app/Contents/Helpers/UnityYAMLMerge

Tip

To access this folder from the macOS Finder, right-click

Unity.app

and select Show Package Contents.

On Linux:


~/Unity/Hub/Editor/<version>/Editor/Data/Tools/UnityYAMLMerge

Configuration file locations

UnityYAMLMerge reads the

mergespecfile.txt

and

mergerules.txt

configuration files from the following folders:

Windows and Linux: the same
```
Tools
```
folder as UnityYAMLMerge, for example
```
<Unity installation>\Editor\Data\Tools
```
.

macOS:

Unity.app/Contents/Resources/UnityYAMLMerge

Set up for Unity Version Control

To add UnityYAMLMerge as a merge tool in the Unity Version Control client:

In the Unity Version Control desktop client, open Preferences and select Merge tools.
Select Add.
Select Custom extension and enter
```
.unity;.prefab
```
.
In External tool, select Unity Smart Merge. This option is available in Unity Version Control 11.0.16.10303 and later. The client fills in the command with the path to UnityYAMLMerge in one of your installed Unity Editors. If you remove that Editor version later, update the path.

To use your own command instead, select Custom and enter:
```
"<path to UnityYAMLMerge>" merge -p "@basefile" "@sourcefile" "@destinationfile" "@output"
```
For
```
<path to UnityYAMLMerge>
```
, refer to Locate UnityYAMLMerge.
Select Save next to the command field to load the new rule in the list.
Use the up arrow to move the new rule above the
```
$text
```
rule. Unity Version Control applies rules from top to bottom, and scene and prefab files are text files, so the new rule must come first.
Select Save at the bottom of the window to save your changes.

Set up for P4V

To resolve conflicts from inside the Unity Editor, refer to Perforce instead.

To merge scene and prefab files with UnityYAMLMerge when you resolve conflicts in P4V:

In P4V, go to Edit > Preferences (macOS: P4V > Preferences) and select Merge.
Under Specify merge application by extension (overrides default), select Add.
In Extension, enter
```
.unity
```
.
In Application, enter the path to UnityYAMLMerge. For more information, refer to Locate UnityYAMLMerge.
In Arguments, enter
```
merge -p %b %1 %2 %r
```
.
Select Save.
Repeat these steps for the
```
.prefab
```
extension.

Set up for Git

Add the following text to your repository's

.git/config

file. To use it in all your repositories, add it to your global

~/.gitconfig

file instead:


[merge]tool = unityyamlmerge[mergetool "unityyamlmerge"]trustExitCode = falsecmd = '<path to UnityYAMLMerge>' merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED"

For

<path to UnityYAMLMerge>

, refer to Locate UnityYAMLMerge.

Set up for Mercurial

Add the following text to your

.hgrc

file:


[merge-patterns]**.unity = unityyamlmerge**.prefab = unityyamlmerge[merge-tools]unityyamlmerge.executable = <path to UnityYAMLMerge>unityyamlmerge.args = merge -p --force $base $other $local $outputunityyamlmerge.checkprompt = Trueunityyamlmerge.premerge = Falseunityyamlmerge.binary = False

For

<path to UnityYAMLMerge>

, refer to Locate UnityYAMLMerge.

Set up for SVN

Add the following to your

~/.subversion/config

file:


[helpers]merge-tool-cmd = <path to UnityYAMLMerge>

For

<path to UnityYAMLMerge>

, refer to Locate UnityYAMLMerge.

Set up for TortoiseGit

To set up TortoiseGit:

In Preferences, add an advanced merge tool.
In Extension, enter
```
.unity
```
.

In External Program, enter:


"<path to UnityYAMLMerge>" merge -p "%base" "%theirs" "%mine" "%merged"

For

<path to UnityYAMLMerge>

, refer to Locate UnityYAMLMerge.

Follow the same procedure to add the
```
.prefab
```
extension.

Set up for SourceTree

To set up SourceTree:

In Tools, add a custom merge tool for diff.
In Merge Command, enter the path to UnityYAMLMerge. For more information, refer to Locate UnityYAMLMerge.
In Arguments, enter
```
merge -p $BASE $REMOTE $LOCAL $MERGED
```
.

UnityYAMLMerge command-line reference

Version control tools call UnityYAMLMerge with the

merge

command:


UnityYAMLMerge merge [options] <base> <theirs> <mine> [<output>]

UnityYAMLMerge supports the following options:

Option	Description
`-p`	Premerge the file. UnityYAMLMerge merges everything it can, then opens the fallback merge tool with premerged files that contain only the remaining conflicts.
`-l`	Resolve conflicts with the theirs version.
`-r`	Resolve conflicts with the mine version.
`-h`	Run in headless mode, with no error dialogs.
`-i <file>`	Resolve conflicts with a merge file.
`-o <file>`	Write conflicts to a file.
`--rules <file>`	Use a custom merge rules file instead of the default `mergerules.txt` .
`--fallback <file>`	Use a custom fallback spec file instead of the default `mergespecfile.txt` . Set to `none` to disable fallback tools.
`--force`	Merge files even if their extension isn't `.unity` , `.prefab` , or `.meta` .
`--describe`	Include a description of the merge in the `-o` file.
`--nomappinginoneline`	Deprecated. This argument has no effect, because Unity always serializes inline mappings on one line.

Configure merge rules

To customize how UnityYAMLMerge merges files, edit the

mergerules.txt

file. For its location, refer to Configuration file locations.

Arrays

The arrays configuration section tells UnityYAMLMerge to treat the specified path as an array: either as a

set

with a key value, or as a

plain

array without key values. The default for all arrays is a hybrid mode that tries to match with some known heuristics.

Each rule starts with a mode:

set

plain

Default array rules:


[arrays]set *.GameObject.m_Component *.fileIDset *.Prefab.m_Modification.m_Modifications target.fileID target.guid propertyPathplain *.MeshRenderer.m_Materialsplain *.Renderer.m_Materials

Exclusions

The exclusions configuration section indicates which paths to exclude from merging. If both sides modify the same path, UnityYAMLMerge treats the change as a conflict and prompts you to resolve it.

Each rule starts with one of the following modes:

include

exclude

includeIfContains

, or

excludeIfContains

Default exclusion rules:


[exclusions]exclude *.MeshRenderer.m_Materials.*exclude *.SpriteRenderer.m_Materialsexclude *.SpriteRenderer.m_Colorinclude *.ParticleSystem.InitialModuleexclude *.ParticleSystem.*exclude *.ParticleSystem.InitialModule.*#excludeDepend *.MonoBehaviour m_Script ^m_excludeIfContains *.MonoBehaviour.* x y zexcludeIfContains *.MonoBehaviour.* r g b

Comparisons

The comparisons section lets UnityYAMLMerge ignore negligible differences between float values. When enabled, UnityYAMLMerge compares floating-point values relative to their magnitude, to account for relative error. You can configure comparison in the following ways:

```
float <float value to compare>
```
: Sets epsilon to a default value close to machine epsilon.
```
float <float value to compare> <relative comparison value and absolute cutoff>
```
: Uses one value as both the relative comparison value and the absolute comparison cutoff.

float <float value to compare> <relative comparison value> <absolute comparison cutoff>

: Sets the relative comparison value and the absolute comparison cutoff separately.

The relative comparison value determines epsilon and how the comparison scales with the size of the values' relative error. The absolute comparison cutoff determines how far from zero a value must be before the comparison switches from absolute to relative.

Note

Comparison values must be between float epsilon (

0.00000011921

) and

1.0

Note

Don't indent rule or section lines. If you copy the commented example from

mergerules.txt

, remove the leading tab as well as the

character. Otherwise, UnityYAMLMerge reports an invalid rule format error.

Comparison examples:


[comparisons]float *.Transform.m_LocalPosition.x 0.0000005float *.Transform.m_LocalPosition.y 0.0000005float *.Transform.m_LocalPosition.z 0.0000005float *.Transform.m_LocalRotation.x 0.00005 0.001float *.Transform.m_LocalRotation.yfloat *.Transform.m_LocalRotation.z 0.00005 0.001float *.Transform.m_LocalRotation.w

Unity Engine

User Manual

Script Reference

Unity Engine

Smart merge

Merging capabilities

When to use smart merge

Set up smart merging in Unity

Unity Version Control

Perforce

Set up UnityYAMLMerge in your tools

Locate UnityYAMLMerge

Configuration file locations

Set up for Unity Version Control

Set up for P4V

Set up for Git

Set up for Mercurial

Set up for SVN

Set up for TortoiseGit

Set up for SourceTree

UnityYAMLMerge command-line reference

Option

Description

Configure merge rules

Arrays

Exclusions

Comparisons

Additional resources