UVCS Conflict Guide

How to Resolve Unity Version Control Merge Conflicts

To resolve a Unity Version Control merge conflict, keep the merge active, identify the base, source, and destination contributors, inspect the asset with Unity-aware context, choose only the decisions you can justify, preview the result, validate it in the project Unity version, and check in the merge only after the asset opens cleanly.

Resolve a UVCS conflict step by step

1. Do not discard the merge state. Keep the pending merge active so UVCS can still provide the three contributors.
2. Identify the conflicted Unity asset. Separate text-serialized scenes, prefabs, materials, and .asset files from non-mergeable binary assets.
3. Preserve base, source, and destination. Base is the common ancestor, destination is your current side, and source is the incoming side.
4. Open the configured merge tool. Use the UVCS Mergetool for ordinary text or a Unity-aware tool for scene and prefab structure.
5. Review every unresolved semantic decision. Check hierarchy, references, prefab overrides, component ownership, reorders, and delete-versus-edit cases.
6. Preview before writing. Confirm that both intended change sets are represented and that no conflict markers remain.
7. Validate in Unity. Open the affected asset, inspect Console errors, missing scripts, references, and prefab connections, then run relevant project tests.
8. Finish the UVCS merge. Mark the file resolved and check in the merge only after validation passes.

Understand UVCS 3-way merge terms

These labels describe roles in one merge operation, not ownership or correctness. The source is not automatically right, and the destination is not automatically safer.

Why scenes and prefabs need more than line selection

UVCS can show the three file contributors, but Unity scenes and prefabs encode object graphs. A short YAML edit can change a GameObject parent, a local object reference, a prefab source link, or a component's serialized property. Conversely, a simple hierarchy move can touch many lines.

A workflow such as MergeSight semantic UVCS conflict review keeps the 3-way contributors visible while presenting changed objects, components, properties, hierarchy, GUIDs, fileIDs, and references. It should complement UVCS, not replace its branch or changeset model.

Choose direct loading or an external wrapper

MergeSight can detect UVCS conflicts through cm status. If the client exposes complete contributor revision metadata, it can load the sides directly. If that metadata is incomplete, configure the supplied interactive UVCS/Plastic merge wrapper so the client passes all five required values:

ancestor  destination  source  output  item-path

The wrapper creates a local request for an already-open Unity Editor, opens Merge Mode, waits for Apply or Cancel, and returns the result to UVCS. The auto-safe CLI wrapper is also available for cases where every decision is engine-proven safe.

Validation checklist before check-in

• The result contains no <<<<<<<, =======, or >>>>>>> markers.
• Every intended object addition, removal, reparent, and reorder is present.
• Prefab instances still point to the correct source and preserve intended overrides.
• GUID and local fileID references resolve to existing assets or objects.
• No missing scripts, hierarchy errors, or component ownership problems were introduced.
• The scene or prefab opens and saves in the project's exact Unity version.
• The merged changeset contains only the intended files and their matching .meta files.

Reduce future UVCS conflicts

Use Smart Locks for genuinely non-mergeable binary assets. For text-serialized scenes and prefabs, choose between locks and merges based on overlap risk: lock a high-risk monolithic scene during a coordinated edit, but keep ordinary prefab and small scene changes reviewable and mergeable.

Short-lived branches, small changesets, scene ownership, additive scene boundaries, prefab-first workflows, and pre-merge semantic review all reduce the amount of intent that must be reconstructed during conflict resolution.

FAQ

How do I resolve a scene conflict in Unity Version Control?

Keep the UVCS merge active, preserve base, destination, and source contributors, review the scene with hierarchy and reference context, preview and validate the result in Unity, then mark it resolved and check in the merge.

What are source and destination in a UVCS merge?

Destination is the branch or workspace receiving changes, similar to Ours. Source is the branch or changeset being merged, similar to Theirs. Base is their common ancestor.

Should I use Smart Locks for every Unity scene?

No. Locks are useful for high-risk or non-mergeable work, but blanket scene locks can reduce parallel work. Text-serialized scenes can often be merged when ownership, review, and validation are strong.

Can MergeSight resolve UVCS conflicts automatically?

MergeSight can auto-resolve only engine-proven safe decisions. Ambiguous mappings, both-edited values, delete-versus-edit cases, and unsupported conflict shapes stay unresolved until a human chooses.

Why does a resolved UVCS conflict still fail in Unity?

A file can be syntactically valid while containing broken references, missing scripts, wrong hierarchy, lost overrides, or an unintended source/destination choice.

Summary

Preserve context

Keep base, destination, and source available until every decision is understood.

Review Unity meaning

Inspect hierarchy, ownership, overrides, GUIDs, fileIDs, and references instead of only lines.

Validate before check-in

Preview, open in Unity, run checks, and only then complete the UVCS merge.

The safe stopping condition is not 'the conflict dialog closed'; it is 'the intended Unity asset opens, validates, and can be explained.'

Next step

For a non-conflicting review, compare the relevant sources first with the UVCS changeset scene comparison workflow.