How We Resolve Merge Conflicts in Unity Scene Files

Unity scene files look like text. They are stored as YAML, and YAML is human-readable in theory. In practice, a Unity scene file for a medium-complexity level is 50,000 to 200,000 lines of auto-generated markup describing every object in the hierarchy, every component on every object, every property on every component, and all the GUID references that tie them together.

When two people edit the same scene and both commit, you get a merge conflict. When that happens in a normal text file, you open a diff tool, read the changes, and make a decision. When it happens in a Unity scene, you get a wall of YAML that is not meaningfully human-readable without understanding Unity's internal object model. The conflict markers land in the middle of component property blocks that were never meant to be read as text.

Why Scene Conflicts Are Different

A standard Git merge conflict in a C++ file looks like this: line 42 was changed one way on branch A and a different way on branch B. You read both versions, understand the intent, and pick the right one.

A Unity scene conflict looks like hundreds of GUIDs and float values, some of which have conflict markers in the middle of property blocks. The conflict might be two designers placing a different prop at a certain position, but the actual conflict text is their respective Transform component data serialized to YAML. The conflict resolution is conceptually simple — "use this position" — but technically messy, because the conflict markers may split a component block and produce a file that Unity cannot parse.

Get it wrong and the scene will not load. Get it partially right and the scene loads with corrupt or missing objects. There is no easy "accept both changes" option.

The Smart Merge Tool

Unity ships a tool called Smart Merge (also called UnityYAMLMerge). It is a three-way merge driver that understands Unity's serialization format. Instead of treating the scene file as generic text, it parses the YAML into Unity objects, applies changes at the object level, and serializes the result back to YAML.

To use it, configure it as your merge driver in Git:

[merge "unityyamlmerge"]
  name = Unity SmartMerge
  driver = 'C:/Program Files/Unity/Hub/Editor/%version%/Editor/Data/Tools/UnityYAMLMerge.exe' merge -p %O %B %A %A
  recursive = binary

And in your .gitattributes:

*.unity merge=unityyamlmerge
*.prefab merge=unityyamlmerge
*.asset merge=unityyamlmerge

This does not solve every conflict. Smart Merge handles most straightforward cases — two designers modifying different objects in the same scene — automatically. But it cannot automatically resolve conflicts where both developers modified the same GameObject or the same component property. Those still require manual review.

Manual Resolution When Smart Merge Fails

When Smart Merge cannot auto-resolve, you need to open the scene in Unity and decide what to keep. The process:

1. Accept the conflict markers from Smart Merge, which marks unresolvable conflicts with == and >>>> blocks
2. Open the scene in Unity — it will likely load with errors or missing objects
3. Use the Unity Editor to manually reconstruct the conflicted objects by comparing against the two source branches
4. Save, commit

This is slow. For a complex scene with multiple simultaneous conflicts, it can take hours.

The Better Answer: Do Not Let Conflicts Happen

The most effective approach to Unity scene conflicts is preventing them rather than resolving them. This means:

Lock scenes before editing

Before a designer opens a scene file in Unity to work on it, they lock it in version control. No one else can make changes to that scene until the lock is released. The workflow is sequential — only one person edits a scene at a time.

This feels like it should slow work down. In practice, for most projects, scenes are not being edited by multiple people simultaneously that often. The slowdown from sequential edits is smaller than the time lost to resolving conflicts when concurrent edits collide.

Split scenes by ownership

Instead of one scene per level, use Unity's additive scene loading to split a level into multiple subscenes — one per area of ownership. The environment artist owns the landscape scene. The level designer owns the gameplay layout scene. The lighting artist owns the lighting scene. Each person can edit their scene independently without touching anyone else's.

This requires some architectural planning upfront, but it is the most scalable approach for larger levels with multiple contributors.

Commit frequently, merge early

The longer a change sits on a branch without merging, the more likely it is to conflict with concurrent work. Short-lived branches and frequent integration reduce conflict probability.

If your scene branch is more than 48 hours old, the integration work is already accumulating. Merge it or rebase it before it gets worse.

What Actually Helps

Smart Merge is worth configuring. It handles the routine cases and reduces manual work significantly. File locking is worth implementing — the operational cost of sequential edits is lower than the cost of resolving conflicts under production pressure.

For teams using Diversion, scene-level conflict detection is integrated into the review workflow. Before a merge is approved, the conflict resolver identifies which objects were modified in both branches and flags unresolvable conflicts for review. The asset locking is visible inside the Unity Editor — no command line required.

Scene conflicts in Unity are a solved problem, but only if you set up the right tooling before you need it. Most studios set it up for the first time during a conflict, which is the worst possible moment to learn.