Unity Scene Conflict Guide

How to Resolve Unity Scene Merge Conflicts in Git

A practical guide to resolving Unity scene conflicts in Git with Smart Merge, semantic review, preview, and validation.

Resolve a Unity scene merge conflict step by step

1. Keep the conflict state intact. Run git status --short, identify each conflicted .unity file, and do not stage a file just to hide the conflict.
2. Preserve all three inputs. Base is the common ancestor, Ours is the current branch, and Theirs is the branch being merged. Avoid replacing the complete scene with one side before you know what each branch changed.
3. Run UnityYAMLMerge. Use the project's configured Git mergetool for the conflicted scene. If it is not configured yet, follow the UnityYAMLMerge setup guide for Git.
4. Classify what remains. Treat hierarchy moves, sibling reorders, changed references, prefab-instance edits, component ownership, and delete-versus-edit cases as decisions that require Unity context.
5. Review Base/Ours/Theirs semantically. A workflow such as MergeSight visual scene conflict review can expose changed GameObjects, hierarchy paths, references, and components without requiring the reviewer to reconstruct the scene from YAML lines.
6. Inspect the proposed output before staging. Check the merged diff, confirm that no conflict markers remain, and verify that the intended changes from both branches are still present.
7. Validate in the project's Unity version. Open the affected scene, inspect the Console, hierarchy, missing scripts, object references, prefab connections, and any project-specific EditMode or PlayMode checks.
8. Stage only the validated result. Add the scene to Git after review and validation, then let CI repeat the checks that can be automated.

Why scene merges are hard

Git merges text, while Unity loads a graph of GameObjects, components, hierarchy, and references. That difference creates three common review problems:

• Hierarchy: moves and reorders can touch many YAML lines, so the intended parent and sibling order are difficult to reconstruct.
• References: a small GUID or fileID change can retarget a material, prefab, script, or scene object.
• Mixed edits: one branch may move an object while another edits it, creating a structural decision rather than a simple field conflict.

A merged file can parse and still contain the wrong hierarchy, a broken reference, or lost prefab state. Treat a clean text result as a candidate that still needs review.

Review checklist before staging the merged scene

Before marking a Unity scene conflict as resolved, confirm:

• Every intended added, modified, moved, and removed GameObject is accounted for.
• Parent-child structure, sibling order, and component ownership match the intended scene.
• Changed local and cross-asset references still point to the correct targets.
• Prefab instances remain connected and intentional overrides are preserved.
• No conflict markers, missing scripts, or broken references remain.
• The merged scene opens and saves in the Unity version used by the project.

This is the operational difference between a merge workflow that only finishes and one that produces a scene the team can trust.

How to reduce Unity scene merge conflicts in Git

Some scene conflicts are unavoidable, but teams can reduce the number of risky conflicts and make the remaining ones easier to resolve.

• Use visible meta files and text serialization so scene changes are inspectable and mergeable.
• Avoid large shared scenes when smaller additive scenes, prefabs, or ownership boundaries would work better.
• Keep high-conflict scene edits short-lived so two branches do not drift for days before merging.
• Review scene changes semantically before merge, especially moves, reorders, references, and prefab instance changes.
• Use CI checks to catch unresolved conflict markers, broken references, missing scripts, and unsafe merge state before main.
• Use Base/Ours/Theirs context for hard conflicts instead of blindly accepting whichever YAML block looks less noisy.

If the immediate problem is understanding a pull request diff rather than resolving a conflict, start with Unity Scene Diff: Raw YAML vs Semantic Review. If the problem is conflict resolution itself, semantic review should feed into the merge decision.

FAQ

How do I resolve a Unity scene merge conflict in Git?

Keep the conflict state and run UnityYAMLMerge. Inspect unresolved Base/Ours/Theirs decisions, preview the output, validate the scene in Unity, and then stage the file.

When should I use UnityYAMLMerge for a scene conflict?

Use it for text-serialized .unity conflicts after Git cannot complete the merge cleanly. Ambiguous hierarchy, reference, reorder, delete-versus-edit, and prefab-instance decisions still require review.

Why can a resolved Unity scene conflict still break later?

A line-level merge can finish without syntax errors while preserving broken references, wrong object ordering, lost prefab connections, or invalid scene structure.

How can teams reduce Unity scene merge conflicts in Git?

Use text serialization, keep scene ownership clear, reduce long-lived parallel edits, review scene diffs semantically, and validate references or missing scripts before accepting merge results.

Try MergeSight

Review the Unity change, not the YAML noise

Use MergeSight after Smart Merge to inspect unresolved scene decisions, preview the output, and validate hierarchy and references.

Get it on the Asset Store See how MergeSight works