Unity Smart Merge Setup

UnityYAMLMerge Guide for Git, Scenes & Prefabs

A complete guide to configuring and using UnityYAMLMerge with Git for text-serialized scenes and prefabs.

Alexandr Rice Follow on X Updated August 27, 2026 6 min read UnityYAMLMerge

Prerequisites: prepare the Unity project for Git

UnityYAMLMerge is Unity's built-in command-line Smart Merge tool for text-serialized .unity scenes and .prefab files. For Git, enable text serialization and visible meta files, locate the binary installed with your Unity Editor, then configure it either as a git mergetool or as an automatic merge driver.

UnityYAMLMerge can only help when the affected assets are stored as text and their identity is preserved. In the Unity Editor, open Edit > Project Settings > Editor and set Asset Serialization > Mode to Force Text. Then open Edit > Project Settings > Version Control and use Visible Meta Files for Git-based projects.

  • Track Assets, Packages, and ProjectSettings, including every asset's .meta file.
  • Confirm that changed .unity and .prefab files are text before branches diverge.
  • Keep each .meta file with its asset when moving or renaming files outside Unity.
  • Do not route .meta files through UnityYAMLMerge; Git should track them to preserve GUID identity.

Unity documents Force Text under Asset Serialization and the current UnityYAMLMerge command contract.

Where UnityYAMLMerge is installed

UnityYAMLMerge ships with the Unity Editor. Replace <version> with the editor version used by the project.

Windows

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

macOS

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

Some older macOS editor versions place the executable under Unity.app/Contents/Tools/UnityYAMLMerge. Check the installed editor package instead of assuming that every Unity version uses the same directory. Running the executable without arguments prints its supported command syntax.

Configure UnityYAMLMerge as a Git mergetool

This is the setup documented by Unity. Put the following configuration in the repository's .git/config or in the user's ~/.gitconfig, replacing the placeholder with the executable path:

[merge]
    tool = unityyamlmerge

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

After a Git merge reports a conflicted scene or prefab, invoke the configured tool explicitly:

git mergetool --tool=unityyamlmerge -- <path-to-conflicted-scene-or-prefab>

Git supplies the common base, current branch, other branch, and output paths through $BASE, $LOCAL, $REMOTE, and $MERGED. Unity's -p option premerges the portions it can resolve and passes remaining conflicts to the fallback configured by Unity's mergespecfile.txt.

Optional: run UnityYAMLMerge as an automatic merge driver

A Git mergetool and a Git merge driver are different. The mergetool runs after Git reports a conflict. A low-level merge driver can run during git merge, but it requires both a committed .gitattributes rule and local driver configuration.

Use a narrow .gitattributes rule for the scene and prefab extensions documented by Unity:

*.unity merge=unityyamlmerge eol=lf
*.prefab merge=unityyamlmerge eol=lf

Then define the matching driver in .git/config or ~/.gitconfig:

[merge "unityyamlmerge"]
    name = Unity Smart Merge
    driver = '<path to UnityYAMLMerge>' merge -h -p --force --fallback none %O %B %A %A
    recursive = binary

The argument order maps Git's ancestor %O, other branch %B, and current branch %A to UnityYAMLMerge's base, theirs, mine, and destination parameters. The driver writes the result back to %A. The --fallback none option prevents an automatic driver from launching an interactive fallback tool.

The driver configuration is not stored in .gitattributes and must be installed for every clone. Confirm both sides of the setup before relying on it:

git check-attr merge -- <path-to-scene-or-prefab>
git config --get-regexp '^merge\.unityyamlmerge\.'

UnityYAMLMerge troubleshooting

Git reports that the merge driver is not found

The attribute name and configuration section must match exactly: merge=unityyamlmerge selects [merge "unityyamlmerge"]. A [mergetool "unityyamlmerge"] section does not define the automatic driver.

The executable path stopped working after an Editor upgrade

Unity Hub installs each editor in a versioned directory, and macOS editor versions may use either Contents/Helpers or Contents/Tools. Resolve the path from the editor version committed in ProjectVersion.txt.

The scene or prefab is still binary

Set Asset Serialization to Force Text, open and resave the affected asset in the project's Unity version, and commit that serialization change before testing merges across branches.

UnityYAMLMerge leaves an unresolved result

That is not a successful merge to bypass. Keep the file conflicted, inspect Base/Ours/Theirs, resolve the remaining Unity-level decision, and validate the output before staging it.

Recommended Unity YAML merge workflow

  1. Let automatic merge handle easy cases. Use UnityYAMLMerge or your configured merge driver for clean, non-overlapping changes.
  2. Classify conflicts by Unity meaning. Identify both-edited, delete-vs-edit, move-vs-edit, reference retarget, and override conflicts.
  3. Review changed assets as objects. Inspect GameObjects, components, hierarchy paths, references, prefab instances, and property paths.
  4. Choose Base, Ours, or Theirs with context. Avoid resolving hard conflicts by only reading whichever YAML block looks shorter.
  5. Preview before write. Generate the merged YAML result before applying it to project files.
  6. Validate after preview. Check for missing scripts, dangling references, invalid hierarchy, unresolved decisions, and suspicious ownership changes.

Validation and CI checks for Unity YAML merges

CI should not only run Unity tests. It should also catch unsafe serialized asset states introduced by a merge.

  • Fail on unresolved Git conflict markers in Unity text assets.
  • Parse changed .unity, .prefab, .asset, and .mat files.
  • Check for missing scripts and dangling references.
  • Validate saved merge plans before preview or apply.
  • Publish Markdown or JSON summaries so reviewers can inspect failures without opening Unity.

MergeSight semantic Unity asset review is built for this part of the workflow: Editor review, 3-way merge context, preview before apply, validation, and CLI commands for CI or merge-driver flows.

FAQ

What is UnityYAMLMerge?

UnityYAMLMerge is Unity's command-line Smart Merge tool for text-serialized .unity scene and .prefab files. It uses Unity-specific merge rules and can run from Git or third-party version-control software.

How do I configure UnityYAMLMerge for Git?

Enable Force Text serialization and visible meta files, locate UnityYAMLMerge inside the installed Unity Editor, then register it as a Git mergetool. An automatic driver additionally requires matching .gitattributes and local [merge "unityyamlmerge"] configuration.

Does .gitattributes alone enable UnityYAMLMerge?

No. The attribute selects a named low-level Git merge driver. Every clone also needs the matching driver configuration; a [mergetool] section is separate and only runs through git mergetool.

What happens when UnityYAMLMerge cannot resolve a conflict?

Premerge mode resolves the portions it can and leaves unresolved decisions for a fallback tool or manual review. Do not stage the result until the scene or prefab has been reviewed and validated in Unity.

Try MergeSight

Review the Unity change, not the YAML noise

Keep UnityYAMLMerge for automatic cases, then use MergeSight for transparent 3-way review, preview, validation, and CI evidence.

Get it on the Asset Store See how MergeSight works
Sources: Unity Smart Merge manual · Git mergetool documentation · Git attributes documentation