Can Git merge Unity scene and prefab files safely?

Git can merge some Unity scene and prefab YAML changes, especially non-overlapping scalar edits. Risk increases when branches change hierarchy, references, prefab overrides, component ownership, or nested prefab structure.

How can CI help with Unity YAML merges?

CI can block unresolved conflict markers, parse changed Unity YAML assets, validate missing scripts and dangling references, verify merge plans, and publish semantic summaries for reviewers.

Unity YAML Merge Guide

Unity YAML Merge: Scenes, Prefabs, Git, and Safe Workflows

Q: What is Unity YAML merge?

Unity YAML merge is the process of combining text-serialized Unity scene, prefab, material, and asset files across branches. It usually involves Git or another VCS, UnityYAMLMerge for automatic Smart Merge, and manual or semantic review for risky conflicts.

Q: When is Unity YAML auto-merge risky?

Unity YAML auto-merge is risky when changes involve delete vs edit, move vs edit, both branches editing the same reference, nested prefab overrides, missing scripts, or GUID and fileID changes that affect object identity.

Unity YAML merge is not just a Git problem. It is the problem of merging serialized Unity object graphs while preserving scene hierarchy, prefab overrides, references, scripts, and asset identity.

7 Wolves June 7, 2026 10 min read Unity YAML merge

Baseline setup for Unity YAML merge

Before discussing tools, make sure the project is actually mergeable as text. Unity YAML merge assumes Unity assets are serialized as text and that meta-file identity is preserved in version control.

Use visible .meta files so asset GUIDs are versioned.
Use text serialization for scenes, prefabs, and other supported assets.
Make sure .unity, .prefab, .asset, .mat, and .meta files are tracked by Git.
Do not delete and recreate assets when a move with the original meta file would preserve identity.

Git attributes shape

A project-specific setup varies, but a common starting point is to tell Git which Unity files should use Unity-aware merge handling.

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

Then wire the merge driver or mergetool to UnityYAMLMerge or to a wrapper used by your team. Unity's manual documents the current UnityYAMLMerge command shape for Git, Perforce, Unity Version Control, and other tools.

Safe vs risky Unity YAML merges

Do not treat every clean YAML merge as safe. Some changes are line-clean but semantically risky.

Decision table

Usually safe

Independent scalar edits on different objects, unrelated material values, or non-overlapping serialized fields.

Needs review

Object moves, sibling reorders, changed references, prefab overrides, or component add/remove operations.

Block until resolved

Delete vs edit, missing scripts, dangling GUIDs, unresolved conflict markers, or ambiguous Base/Ours/Theirs choices.

The key question is not whether YAML parsed. The key question is whether the Unity object graph still means what the team intended.

Example: raw YAML change vs Unity meaning

A Unity YAML merge often exposes low-level identifiers when the reviewer needs Unity-level context.

--- !u!114 &3344556677
MonoBehaviour:
  m_GameObject: {fileID: 9988776655}
  m_Script: {fileID: 11500000, guid: 7e4a8f..., type: 3}
  targetDoor: {fileID: 2211003344}
  openDelay: 0.35

As raw text, this is a changed number and a changed reference. As Unity meaning, it might be:

the DoorTrigger component on Level01/Entrance/Button_A changed its target door
the target changed from a local door object to another object in the scene
the same branch also changed openDelay
the risk is not YAML syntax; the risk is whether the button now opens the intended door

This is why a semantic review layer helps. It converts low-level YAML evidence into reviewable Unity facts.

Recommended Unity YAML merge workflow

Let automatic merge handle easy cases. Use UnityYAMLMerge or your configured merge driver for clean, non-overlapping changes.
Classify conflicts by Unity meaning. Identify both-edited, delete-vs-edit, move-vs-edit, reference retarget, and override conflicts.
Review changed assets as objects. Inspect GameObjects, components, hierarchy paths, references, prefab instances, and property paths.
Choose Base, Ours, or Theirs with context. Avoid resolving hard conflicts by only reading whichever YAML block looks shorter.
Preview before write. Generate the merged YAML result before applying it to project files.
Validate after preview. Check for missing scripts, dangling references, invalid hierarchy, unresolved decisions, and suspicious ownership changes.

CI checks for Unity YAML merges

CI should not only run Unity tests. It should also catch unsafe serialized asset states introduced by a merge.

Fail on unresolved Git conflict markers in Unity text assets.
Parse changed .unity, .prefab, .asset, and .mat files.
Check for missing scripts and dangling references.
Validate saved merge plans before preview or apply.
Publish Markdown or JSON summaries so reviewers can inspect failures without opening Unity.

MergeSight is built for this kind of workflow: semantic review in the Editor, 3-way merge context, preview before apply, validation, and CLI commands for CI or merge-driver flows.

FAQ

What is Unity YAML merge?

It is the process of merging Unity's text-serialized assets, especially scenes and prefabs, across branches in Git or another version control system.

Can Git merge Unity scene and prefab files?

Git can merge the text files, and UnityYAMLMerge can improve scene and prefab merging. But risky object-graph changes still need Unity-aware review and validation.

When is Unity YAML auto-merge risky?

It is risky when branches change hierarchy, references, prefab overrides, missing scripts, object identity, or delete and edit the same object in different branches.

Should Unity YAML merge be automated?

Easy cases should be automated. Ambiguous conflicts should produce a reviewable plan, preview, and validation result rather than silently choosing a side.

Summary

Unity YAML merge means merging Unity's text-serialized assets, especially .unity scene files and .prefab prefab files. Unity provides UnityYAMLMerge for Smart Merge, but teams still need semantic review when branches change hierarchy, references, prefab overrides, or object identity.

The practical workflow is: enable text serialization and visible meta files, configure Smart Merge or a merge driver, review changed assets semantically, preview risky merge results, and validate references or missing scripts in CI before merging to main.

Summary

What Git sees

Text files, line changes, conflict markers, and merge exit codes.

What Unity sees

GameObjects, components, prefab instances, fileIDs, GUIDs, and references.

What teams need

Automatic merge for easy cases, semantic review for risky cases, and CI validation.

Unity YAML merge is safest when automatic merging is paired with human-readable Unity context.

Next step

If you need a tool-level comparison, read UnityYAMLMerge vs MergeSight. If scene diffs are the main pain, continue with Unity Scene Diff: Raw YAML vs Semantic Review. For automation, see Unity Asset Merge Checks in CI.