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