Unity Merge Conflicts in Scenes and Prefabs: Prevent and Fix Them

Two people edit the same scene, one pulls, and git reports a conflict in a file full of fileID and guid lines nobody can read. Pick the wrong side and objects vanish or references break. Unity merge conflicts in scenes and prefabs are one of the biggest pains of working in a team, but most of them can be prevented, and the rest resolved safely. This guide covers the settings, the Smart Merge tool, how to structure scenes and prefabs to avoid collisions, and what to do when a conflict happens anyway.

Why Unity Files Conflict

Scenes, prefabs, materials and ScriptableObjects are saved as YAML text. Each object in a scene is a block with a local fileID, and references between objects are fileIDs plus GUIDs pointing at assets. Git merges line by line. It doesn’t understand that two blocks are separate objects or that a reordered list is still the same list, so it reports conflicts in changes that don’t actually clash.

Worse, a “clean” automatic merge can still be wrong. If git merges two edits that individually were fine but together create a dangling reference, Unity loads a broken scene with no error from git.

Project Settings That Help

Check these in Project Settings > Editor:

• Asset Serialization Mode: Force Text. The default in new projects. Binary scenes can’t be merged at all.
• Version Control Mode: Visible Meta Files. Also the default. Meta files must be in version control.

Commit a .gitattributes that tells git how to treat Unity files. A minimal one:

*.unity    merge=unityyamlmerge eol=lf
*.prefab   merge=unityyamlmerge eol=lf
*.asset    merge=unityyamlmerge eol=lf
*.mat      merge=unityyamlmerge eol=lf
*.anim     merge=unityyamlmerge eol=lf
*.controller merge=unityyamlmerge eol=lf
*.meta     eol=lf

The eol=lf stops Windows and Mac machines fighting over line endings, which otherwise makes every line look changed. The merge=unityyamlmerge part only does something once each developer configures the merge driver below. The git setup guide has a full .gitignore and .gitattributes.

Set Up Smart Merge (UnityYAMLMerge)

Unity ships a merge tool called UnityYAMLMerge that understands Unity’s YAML: it merges by object, not by line. It lives in the Editor install:

• Windows: C:\Program Files\Unity\Hub\Editor\<version>\Editor\Data\Tools\UnityYAMLMerge.exe
• macOS: /Applications/Unity/Hub/Editor/<version>/Unity.app/Contents/Tools/UnityYAMLMerge

Add it as a git merge driver in your global git config (each developer does this once):

git config --global merge.unityyamlmerge.name "Unity SmartMerge"
git config --global merge.unityyamlmerge.driver "'C:/Program Files/Unity/Hub/Editor/6000.0.40f1/Editor/Data/Tools/UnityYAMLMerge.exe' merge -h -p --force %O %B %A %A"
git config --global merge.unityyamlmerge.recursive binary

Adjust the path to your installed version. With this and the .gitattributes lines, git hands Unity files to Smart Merge, which resolves most “fake” conflicts automatically. When it can’t, it leaves the conflict for you, often with a much smaller set of real clashes.

You can also configure it as a mergetool so git mergetool uses it, falling back to a normal diff tool for unresolved parts. Unity’s documentation on Smart Merge includes a mergespecfile.txt for choosing the fallback tool.

Structure Work to Avoid Conflicts

The best conflict is the one that never happens:

• Prefab everything. If the player, enemies, rooms and UI panels are prefabs, the scene file only holds prefab instances and positions. People edit different prefab files instead of the same scene. Nested prefabs make this practical; see the prefabs and variants guide.
• Split scenes. Use additive scenes: one for lighting, one for gameplay systems, one per level area, one for UI. Different people own different scenes.
• Move data out of scenes. Settings, item stats and balancing in ScriptableObjects mean tuning doesn’t touch scene files. The ScriptableObjects guide shows how.
• Communicate. “I’m in Level2 today” in your team chat prevents most scene conflicts.
• Commit and pull often. Small, frequent merges have small conflicts.
• Don’t save scenes you didn’t mean to change. Opening a scene can mark it dirty (for example, when a prefab updated). Check what you’re committing and revert scenes you didn’t intentionally edit.

File Locking for Binary Assets

Textures, audio, models and other binary files can’t be merged at all. If two people edit the same PSD, one person’s work is lost. With Git LFS, you can mark these types as lockable in .gitattributes (*.psd filter=lfs diff=lfs merge=lfs -text lockable) and use git lfs lock before editing. Some teams also lock scenes this way rather than merging them. Unity Version Control (formerly Plastic SCM) and Perforce have built-in locking that many larger teams use for the same reason.

Resolving a Conflict

When a scene or prefab conflict happens and Smart Merge can’t solve it:

1. Don’t open the conflicted file in Unity yet. Unity may try to load a file full of conflict markers, fail, and save a broken version.
2. Decide if one side can simply win. If your changes were small, take theirs and redo yours: git checkout --theirs Assets/Scenes/Level1.unity. Or the reverse with --ours. Note that during a rebase, ours and theirs are swapped.
3. Remember the .meta. If both the asset and its .meta conflict, take the same side for both.
4. If both sides matter, take one side, open Unity, and manually redo the other side’s changes. For prefabs, this is often just a few fields. Hand-editing conflict markers in large YAML files is possible but risky.
5. Open and check. After resolving, open the scene, look for missing references, red prefab instances and Console errors, then commit.

If something went wrong and objects show as missing prefabs, the missing prefab guide shows how to restore the GUID link.

.meta File Conflicts

A conflict in a .meta file almost always involves the guid line or import settings.

• Different GUIDs: the same asset was created twice, or a .meta was regenerated. Pick the GUID that other assets already reference (usually the older one, already in the main branch). Changing it breaks every reference to the other.
• Import settings: two people changed a texture’s compression or a model’s import options. Pick one and reapply the other’s changes in the Inspector.

Troubleshooting

“CONFLICT (content): Merge conflict in Assets/Scenes/Main.unity”

Set up Smart Merge for future merges. For this one, take one side with checkout –ours or –theirs and redo the other’s changes in Unity.

Scene loads with objects missing after a clean merge

Git merged lines into an invalid combination. Revert the merge commit for that file, take one side, and reapply changes manually.

Every line shows as changed

Line endings differ between machines. Add eol=lf in .gitattributes and renormalize.

Smart Merge isn’t being used

The merge driver isn’t configured on that machine, or the path is wrong after a Unity update. Check git config and the .gitattributes lines.

Unity says the scene file is corrupted

It still contains conflict markers. Close Unity, resolve the file in git, then reopen.

FAQ