Unity Scene Conflict Guide

How to Resolve Unity Scene Merge Conflicts in Git

To resolve a Unity scene merge conflict, keep Git's conflict state, run UnityYAMLMerge on the text-serialized .unity file, inspect unresolved Base/Ours/Theirs decisions with scene context, preview the output, validate it in the project's Unity version, and stage the file only after those checks pass.

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.

The core problem: Unity scene meaning is not line-based

Git merge is excellent at combining text. A Unity scene stored as YAML is technically text, but the meaning of that file comes from relationships between objects. A scene merge is rarely just about changed lines. It is about whether a GameObject still lives under the right parent, whether component ownership still makes sense, and whether references still point to the correct targets.

When two branches change the same scene, raw YAML merge has no first-class understanding of scene structure. It sees text chunks. Your team sees cameras, roots, children, components, materials, and references. That gap is where merge pain comes from.

Why raw YAML creates merge noise

A simple scene refactor can generate large textual churn even when the conceptual change is straightforward. A GameObject move, child reorder, or component edit may touch wide parts of the YAML representation. Reviewers then spend time reconstructing what actually changed instead of deciding whether the merge is correct.

This gets worse in scenes with many references. fileID and guid data are visible in YAML, but they are not meaningful at a glance. The file exposes low-level identifiers at exactly the point where humans need high-level context.

Why scene merges often break after a conflict is resolved

A text merge can succeed mechanically and still fail semantically. The merged file may parse, commit, and even pass initial inspection, while preserving the wrong parent-child relationship, hiding a broken reference, or accidentally combining reorder operations in a way that changes runtime behavior.

That is why teams often discover merge problems late: after opening the project in Unity, during QA, or inside CI. The conflict was resolved syntactically, but not meaningfully.

Three scene-specific pain points

1. Hierarchy changes are difficult to reconstruct

Scene review depends on understanding where an object lives in the hierarchy. Text merge strips that away. When branches move objects, add children, or reorder siblings, the reviewer is forced to mentally rebuild scene structure from YAML fragments.

2. References hide their real impact

A changed reference may be small in the file and large in the scene. Material links, object references, prefab instance connections, and serialized fields can all create downstream effects that are invisible in line-by-line conflict resolution.

3. Reorders and moves look like destructive edits

Many merges are not two people editing the same scalar field. They are cases where one branch moved or reordered content while another edited it. In YAML, those situations often look larger and messier than they really are, which leads teams either to panic or to over-trust auto resolution.

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.

Why semantic review matters before semantic merge

Even when merge tooling is the long-term goal, teams benefit first from seeing changes semantically. If you can inspect scene changes with hierarchy-aware context before merge, you reduce ambiguity earlier in the pipeline. That improves review quality, makes conflicts more understandable, and lowers the chance of blindly accepting bad merge output.

That is the practical case for tools like MergeSight: they shift review from raw text to scene meaning, which is exactly where scene merge confidence starts.

FAQ

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

Keep the conflict state, run UnityYAMLMerge, inspect unresolved Base/Ours/Theirs decisions with hierarchy and reference context, preview the output, validate the scene in Unity, and stage it only after those checks pass.

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.

Summary

Resolve

Keep Base/Ours/Theirs, run UnityYAMLMerge, and classify the unresolved Unity-level decisions.

Review

Inspect hierarchy, references, prefab instances, moved objects, and the complete proposed output.

Validate

Open the scene in the project Unity version, check the Console and references, then run project checks.

A Unity scene conflict is resolved only when both the text merge and the intended scene behavior have been verified.

Next step

For tool configuration, use the UnityYAMLMerge guide for Git, scenes, and prefabs. For pull-request review before a conflict occurs, continue with visual Unity scene diff versus raw YAML. For tool selection, compare UnityYAMLMerge and MergeSight workflows.