Unity Scene Merge Conflicts: A Survival Guide for Teams

Scene merge conflicts are the closest thing game development has to stepping on a rake. Everyone knows the rake is there. Everyone has stepped on it before. And every few sprints, two people edit the arena scene on the same day anyway, and Tuesday afternoon disappears into a merge nobody can win.

The worst version isn’t even the conflict git flags. It’s the merge that succeeds textually and produces a scene that loads with quietly broken references, which nobody discovers until Thursday. I’ve billed real hours to that Thursday, on more than one team.

Nothing makes shared scenes painless. But four practices together get you surprisingly close, and they’re cheap enough that I set them up on every team project now.

Why scenes merge so badly

A Unity scene is a single YAML document, often tens of thousands of lines, where every GameObject and component is a block keyed by a numeric fileID, and blocks reference each other by those IDs. Git merges text line by line, with no idea that lines 4,812 and 31,057 describe the same object. Two edits that are semantically independent (you moved a light, I added a button) still collide constantly, and git’s honest attempt at resolving them produces structural soup: duplicated IDs, half-applied components, orphaned references.

So the strategy has two halves: make merges rarer, and make the unavoidable ones mergeable.

Step 0: check your serialization settings

Under Project Settings → Editor, Asset Serialization should be Force Text, and version control mode should show meta files. New projects get this by default, but I still find old projects with binary scenes, and a binary scene can’t be merged by anything. Thirty seconds to check.

Wire up UnityYAMLMerge (the tool you already own)

Unity ships a semantic merge tool with every editor install, and in ten years I’ve joined exactly two teams that had it configured. It merges scenes and prefabs by object instead of by line, which dissolves most of the conflicts that wreck a textual merge.

Two pieces of setup. In .gitattributes:

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

And in your git config:

[merge "unityyamlmerge"]
    name = Unity SmartMerge
    driver = 'UnityYAMLMerge' merge -p %O %B %A %A

The binary lives inside the editor install: Unity.app/Contents/Tools/UnityYAMLMerge on macOS, Editor\Data\Tools\UnityYAMLMerge.exe on Windows (substitute the full path for your install). With that in place, most scene conflicts simply stop being conflicts; the tool reconciles them and only punts to you when two people genuinely changed the same object.

Make scenes thin: the prefab-first workflow

The best merge is the one that never happens, and the way to get there is to make the scene file boring. A thin scene is a hierarchy of prefab instances and almost nothing else; the actual content and wiring live inside prefabs, so the level designer editing the arena layout and the programmer rewiring the boss are touching different files. Prefab variants extend this nicely for theming and per-level overrides.

Push the data even further out and you barely touch shared files at all. Gameplay values that live in ScriptableObjects rather than on scene objects change without the scene file changing, an approach I’ve written about in depth.

Split big scenes additively

For larger levels, one scene per concern, loaded additively: environment, lighting, gameplay, UI. Each sub-scene gets an owner, and the lighting artist stops meeting the level designer in the same file. Unity’s multi-scene editing handles this well, and the ownership boundary does as much work as the technical one.

Which brings up the embarrassingly effective fourth practice: say it out loud. “I’m in the arena scene today” in standup prevents more merge conflicts than any tool in this post. Cheap, unglamorous, works.

When the conflict happens anyway

It still will, occasionally. Two rules for that day. First, never hand-edit conflict markers inside scene YAML unless you actually understand the format; a scene that loads is not evidence the merge was correct. Second, when a merge looks wrong, prefer taking one side wholesale and re-applying the other person’s change in-editor over salvaging the textual merge. Fifteen minutes of redone work beats a corrupted scene you’ll be debugging next week.

The safety net: don’t let a bad merge reach main

Everything above reduces the odds. The safety net is validation in CI, because the failure mode of a bad scene merge (dead references, missing scripts, duplicated components) is exactly the kind of damage that loads without complaint and fails at runtime.

My pipelines run a full-project scan on every merge request using RefSafe Pro’s batchmode CLI, which exits non-zero when issues cross a threshold and exports findings as GitHub Actions annotations or GitLab Code Quality reports, right in the diff view. A broken merge gets caught by a robot on Tuesday instead of a player after launch.

Rake’s still there. You just stop stepping on it. (More Unity time sinks and their fixes in the five problems that eat entire weeks.)