# 3. UnityYAMLMerge / Smart Merge
**Target:** Unity 6000.5+. Part of [[Version Control]]. Requires Force Text from [[1. Serialization Meta and Gitignore]].
## What Smart Merge actually does
**UnityYAMLMerge** merges Unity YAML **semantically** for:
- Scenes — `.unity`
- Prefabs — `.prefab`
- And (per newer docs) `.meta` when asked to
Instead of treating the file as a flat text conflict salad, it understands GameObject / component structure. Conflicts it cannot resolve go to a **fallback** merge tool listed in `mergespecfile.txt`.
Docs:
- Unity 6000.5 Smart merge: https://docs.unity3d.com/6000.5/Documentation/Manual/SmartMerge.html
- Newer manual (Hub install paths, Git block, CLI flags): https://docs.unity.com/en-us/engine/7000.0/manual/get-started/project-configuration/version-control/smart-merge
By default UnityYAMLMerge does **not** treat `.asset`, `.mat`, `.controller`, etc. as first-class merge targets; those go to fallbacks unless you pass `--force` (see command-line reference in the newer manual).
> [!warning] Not verified live on Enceladus
> The path examples and `git mergetool` invocation below were **not** executed against Marshall’s installed Editors. Locate `UnityYAMLMerge.exe` on disk for your exact Hub version (for example `6000.5.x`) before writing global gitconfig.
## When you need it
- Two people (or two branches) edit the **same** scene or Prefab without exclusive locks.
- You merge feature branches that both touched layout / Prefab contents.
If you exclusively lock scenes (UVCS Smart Locks, Perforce checkout, or strict social “one owner”), you may rarely need it — but solo branching still benefits when you merge your own long-lived branches.
## Step 1 — Locate `UnityYAMLMerge.exe` (Windows)
### Unity Hub default (preferred; newer docs)
```text
C:\Program Files\Unity\Hub\Editor\<version>\Editor\Data\Tools\UnityYAMLMerge.exe
```
Replace `<version>` with the Editor folder name Hub installed (example shape only: `6000.5.something` — **use the folder that exists on your machine**).
Same layout is documented for Hub installs in the [7000.0 Smart merge page](https://docs.unity.com/en-us/engine/7000.0/manual/get-started/project-configuration/version-control/smart-merge).
### Legacy / non-Hub paths (still listed in 6000.5 docs)
```text
C:\Program Files\Unity\Editor\Data\Tools\UnityYAMLMerge.exe
C:\Program Files (x86)\Unity\Editor\Data\Tools\UnityYAMLMerge.exe
```
### Confirm
In PowerShell (full cmdlet names):
```powershell
Get-ChildItem -LiteralPath "C:\Program Files\Unity\Hub\Editor" |
Select-Object Name
Get-Item -LiteralPath "C:\Program Files\Unity\Hub\Editor\<your-version>\Editor\Data\Tools\UnityYAMLMerge.exe"
```
Also in that `Tools` folder: `mergespecfile.txt` (fallback tools) and `mergerules.txt` (semantic rules).
## Step 2 — Configure Git mergetool
Unity’s documented Git setup (both 6000.5 and newer manuals) is a mergetool entry. Add to the **repo** `.git/config` or your **user** `.gitconfig`:
```gitconfig
[merge]
tool = unityyamlmerge
[mergetool "unityyamlmerge"]
trustExitCode = false
cmd = 'C:/Program Files/Unity/Hub/Editor/<version>/Editor/Data/Tools/UnityYAMLMerge.exe' merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED"
```
Notes:
- Use **forward slashes** or properly escaped paths in the `cmd` string.
- Argument order `"$BASE" "$REMOTE" "$LOCAL" "$MERGED"` matches Unity’s Git instructions.
- `-p` = **premerge**: merge what it can, then hand remaining conflicts to the fallback tool.
Example using `git config` (adjust path):
```bash
git config --global merge.tool unityyamlmerge
git config --global mergetool.unityyamlmerge.trustExitCode false
git config --global mergetool.unityyamlmerge.cmd "'C:/Program Files/Unity/Hub/Editor/<version>/Editor/Data/Tools/UnityYAMLMerge.exe' merge -p \"$BASE\" \"$REMOTE\" \"$LOCAL\" \"$MERGED\""
```
### After a conflicted merge
```bash
git status
git mergetool --tool=unityyamlmerge -- path/to/ConflictedScene.unity
# fix remaining conflicts in the fallback UI if prompted
git add path/to/ConflictedScene.unity
git commit # completes the merge commit if one is pending
```
## Step 3 — Optional Editor script helper (path discovery)
This does **not** replace gitconfig; it helps you print the path for the Editor you currently have open. Put under an `Editor` folder (see [[Custom Inspectors and Editor Tooling]] for Editor assembly habits).
```csharp
#if UNITY_EDITOR
using UnityEditor;
using UnityEngine;
using System.IO;
public static class UnityYamlMergePathMenu
{
[MenuItem("Tools/Version Control/Log UnityYAMLMerge Path")]
private static void LogPath()
{
// EditorApplication.applicationContentsPath points at .../Editor/Data
var tools = Path.Combine(EditorApplication.applicationContentsPath, "Tools");
var exe = Path.Combine(tools, "UnityYAMLMerge.exe");
Debug.Log(File.Exists(exe)
?
quot;UnityYAMLMerge: {exe}"
: quot;UnityYAMLMerge not found under {tools}");
EditorUtility.RevealInFinder(tools);
}
}
#endif
```
> Not run live here — compile/run in your project to confirm.
## Step 4 — Fallback tools (`mergespecfile.txt`)
UnityYAMLMerge ships `mergespecfile.txt` beside the exe. It lists external tools for unresolved conflicts / unknown types so you can set UnityYAMLMerge as the **primary** mergetool even when Git does not pick by extension.
Edit carefully; keep a backup copy outside the Hub folder if you customize (Hub upgrades can replace Tools content depending on install layout). Prefer pointing Git at the Tools folder of a **pinned** Editor version your team standardizes on.
## Step 5 — Merge rules (`mergerules.txt`)
`mergerules.txt` tunes arrays, exclusions, and float comparisons. Defaults (from Unity docs) include treating `GameObject.m_Component` as a keyed set, materials arrays as plain arrays, and excluding some renderer/particle paths from auto-merge so true conflicts surface.
Do **not** invent rules casually. If you customize:
- Prefer a **copy** referenced with `--rules` (newer CLI) rather than silently editing the Hub install when possible.
- Newer docs warn: **do not indent** rule lines; copying commented samples with leading tabs causes invalid rule format errors.
- Float comparison values must stay between ~machine epsilon and `1.0`.
Example shape from Unity’s documentation (illustrative of format only):
```text
[arrays]
set *.GameObject.m_Component *.fileID
set *.Prefab.m_Modification.m_Modifications target.fileID target.guid propertyPath
plain *.MeshRenderer.m_Materials
plain *.Renderer.m_Materials
[exclusions]
exclude *.MeshRenderer.m_Materials.*
exclude *.SpriteRenderer.m_Materials
exclude *.SpriteRenderer.m_Color
include *.ParticleSystem.InitialModule
exclude *.ParticleSystem.*
exclude *.ParticleSystem.InitialModule.*
excludeIfContains *.MonoBehaviour.* x y z
excludeIfContains *.MonoBehaviour.* r g b
[comparisons]
float *.Transform.m_LocalPosition.x 0.0000005
float *.Transform.m_LocalPosition.y 0.0000005
float *.Transform.m_LocalPosition.z 0.0000005
```
## Step 6 — CLI cheat sheet (from newer Unity docs)
```text
UnityYAMLMerge merge [options] <files...>
```
Useful options documented by Unity:
| Option | Meaning |
|---|---|
| `-p` | Premerge, then fallback for leftovers |
| `-h` | Headless (no error dialogs) |
| `-l` / `-r` | Resolve conflicts theirs / mine |
| `--force` | Merge even if extension is not `.unity` / `.prefab` / `.meta` |
| `--fallback none` | Disable fallback tools (automation) |
| `--rules <file>` | Custom `mergerules.txt` |
| `--fallback <file>` | Custom `mergespecfile.txt` |
Full table: [UnityYAMLMerge command-line reference](https://docs.unity.com/en-us/engine/7000.0/manual/get-started/project-configuration/version-control/smart-merge).
## Step 7 — Editor Project Settings vs Git
**Edit > Project Settings > Version Control → Smart Merge** (Off / Premerge / Ask) applies when Mode is a Unity-integrated VCS such as **Perforce** (and historically related flows). For **plain Git**, the Editor Mode is typically **Visible Meta Files** and **Git itself** invokes UnityYAMLMerge via mergetool — the Smart Merge dropdown is not your Git switch.
For **Unity Version Control**, the UVCS client’s own merge-tool preferences matter; selecting a merge tool inside Unity Preferences does not automatically wire UVCS to UnityYAMLMerge ([newer Smart merge docs](https://docs.unity.com/en-us/engine/7000.0/manual/get-started/project-configuration/version-control/smart-merge)).
## SourceTree / TortoiseGit
Unity documents GUI client setups (SourceTree custom merge command `merge -p $BASE $REMOTE $LOCAL $MERGED`, TortoiseGit advanced merge by extension). If you use GitHub Desktop, mergetool behavior is more limited — keep CLI mergetool configured for hard scene conflicts (see [[5. Clients and UVCS Comparison]]).
## Next
[[4. Conflicts Prefabs and Branching]] — avoid needing Smart Merge as often as possible.