MergeSight Download PDF

Official user guide

Review and merge Unity assets with context.

Install MergeSight, understand semantic changes, resolve BASE / OURS / THEIRS decisions, and preview the result before writing it.

Unity 2022 LTS Unity 2023 LTS Unity 6 Editor only
Start with installation Open PDF
Before you begin Use Force Text serialization.

MergeSight reads text-serialized Unity assets. Binary scenes and prefabs cannot be reviewed or merged semantically.

Edit > Project Settings > Editor > Asset Serialization

01 / Overview

What MergeSight does

MergeSight turns text-serialized Unity assets into a Unity-aware review and merge model.

Review

Understand changes between revisions.

Inspect objects, components, hierarchy, properties, and references with aligned Before / After values.

3-way Merge

Resolve conflicting versions.

Compare BASE, OURS, and THEIRS in semantic context, then inspect the composed result.

Assets.unity, .prefab, .asset, .mat
VCSGit, Plastic/UVCS, Perforce, SVN
RuntimeNo runtime components
Terminology

BASE is the common ancestor. OURS is your side. THEIRS is the incoming side.

02 / Setup

Installation and first launch

  1. Import

    Import the Asset Store package into your Unity project.

  2. Serialize

    Set Asset Serialization > Mode to Force Text.

  3. Open

    Choose Tools > MergeSight > New Window.

  4. Select a workflow

    Use Review for comparison work or 3-way Merge for an active conflict.

Safe default

Git can be detected locally. Startup detection for SVN, Perforce, and Plastic/UVCS is opt-in.

03 / Review

Review Mode quick start

1 Asset list 2 Comparison controls 3 Semantic details
  1. Choose Review at the top of the window.
  2. Select From and To sources. Git supports branches, commits, and the Working Tree.
  3. Select an asset in the left panel.
  4. Expand the semantic tree to inspect objects, components, and properties.
Tip

Use a branch or commit on the left and Working Tree on the right to review local changes before committing them.

04 / Review

Understanding semantic changes

1 Changed asset 2 Unity hierarchy 3 Before / After
Object

A GameObject or serialized Unity object.

Component

A group of fields owned by one component.

Property

The serialized value that changed.

Reference

A linked asset or local Unity object.

Read top to bottom

Start with the object, expand the changed component, then confirm the exact Before / After value.

05 / Review

Search and filters

1 Asset filters 2 Search and change filters 3 Filtered result
  • Filter assets by name, path, type, or VCS status.
  • Search the semantic tree by object, component, or property name.
  • Use Change for added, removed, or modified entries.
  • Use Kind for objects, components, properties, or references.
  • Clear filters before assuming an asset or change is missing.

06 / Review

Complex assets and references

1 Changed assets 2 Unity hierarchy 3 Aligned values

Large scenes can contain hierarchy moves, component edits, prefab overrides, and references in one review. MergeSight keeps related rows under their Unity owners.

Fail-safe behavior

If MergeSight cannot prove a safe interpretation, it reports the limitation instead of silently inventing a result.

07 / Merge

3-way Merge quick start

1 Conflicted asset 2 Merge actions 3 BASE / OURS / THEIRS
  1. Open a conflicted supported asset and switch to 3-way Merge.
  2. Expand conflict rows and read their Unity hierarchy context.
  3. Compare BASE, OURS, and THEIRS for each unresolved row.
  4. Choose a side for each decision, or use Take All when one side is correct for the complete asset.
  5. Inspect the composed result before Apply.
Do not guess

A clean-looking text merge can still break ownership, hierarchy, or references.

08 / Merge

Resolve property conflicts

1 Context 2 BASE 3 OURS 4 THEIRS
1 Selected result 2 Apply readiness

Decision flow

  1. Read the property and parent context.
  2. Use BASE to understand the original value.
  3. Choose OURS or THEIRS.
  4. Confirm the unresolved count decreases.

09 / Merge

Structural conflicts

Reparent

1 Competing parent relationships 2 Structural context

A reparent operation changes hierarchy ownership, not only a scalar field. Confirm which parent should own the object and inspect dependent Transform relationships.

Delete vs edit

1 Component decision 2 Dependent context

Keeping the edited side preserves the component and its change. Choosing deletion removes the component and makes its edited fields irrelevant.

10 / Merge

Reference conflicts

Asset reference conflict

External assets use GUID-based identity. Objects inside the same scene or prefab use local file IDs. Choose the intended object, then preview the result so Unity can confirm that the reference resolves.

11 / Apply

Preview and Apply

Result verification
  1. Resolve every required merge decision.
  2. Choose Output > Preview Result Asset to inspect the composed asset without overwriting the original conflict.
  3. For scenes, save current work and confirm the scene-opening prompt.
  4. Optionally use Output > Result Diff for a final semantic comparison.
  5. Return to MergeSight and choose Apply.
  6. Open the real asset in Unity and run the project checks appropriate for the change.
Safety

Apply is blocked while required decisions remain. MergeSight creates a backup before writing the merged result.

12 / Integration

VCS integration

ProviderReviewConflict loading
GitBranches, commits, Working TreeLocal unmerged stages
Plastic / UVCSChangesets and supported working-copy sourcesWrapper-first when all three sides are unavailable directly
PerforceHave revision, working copy, supported changelistsDirect detection where possible; P4V/P4MERGE wrappers supported
SVNBASE, Working Copy, supported revisionsLocal conflict side files or wrapper

Open integration setup

Use Tools > MergeSight > VCS Integration Setup. The Setup tab contains provider actions; Advanced / Troubleshooting contains wrapper commands, diagnostics, and raw paths.

Startup detection

Git detection is local by default. Enable startup detection explicitly for Plastic/UVCS, Perforce, or SVN.

13 / Help

Troubleshooting and limitations

Asset missing from Review

Clear filters, confirm the selected sources differ, and confirm the file is a supported text-serialized Unity asset.

Apply is disabled

Expand unresolved rows and choose every required BASE / OURS / THEIRS decision.

Only raw conflict markers

Git stages or provider side files were unavailable. Restore a real VCS conflict or fix markers manually.

Reference is unresolved

Confirm the asset exists, its GUID is stable, and the intended local object still exists.

Provider is not detected

Check the provider CLI, credentials/workspace, startup setting, and diagnostics in VCS Integration Setup.

Result preview opens a scene

Save current scenes first. Scene previews open only after an explicit warning and Unity's save prompt.

Known boundaries

  • Binary Unity assets cannot be reviewed or merged semantically.
  • Ambiguous or unsupported YAML structures fail closed and require manual review.
  • Provider capabilities differ; wrappers may be required to supply BASE, OURS, and THEIRS.
  • Validate important merged scenes and prefabs inside Unity before committing.
Support request

Include the Unity version, VCS provider, asset type, a short reproduction, and the MergeSight diagnostic report. For help and questions, join the MergeSight Discord community.

Offline reference

Keep the guide with your project.

The same documentation is available as a numbered, 16-page PDF for offline use and the Asset Store package.

Download PDF