Merge conflictsAlways fixable

Resolve a Unity scene or prefab merge conflict

Two people edited the same Unity scene — how do I merge it without losing work?

Short answer

Unity scenes and prefabs are YAML, so they can be merged — but only if Force Text serialization is on and you've registered Unity's own UnityYAMLMerge tool with Git. Without that setup Git mangles them, and the only safe resolution is to pick one side entirely.

quick fix
git checkout --ours Assets/Scenes/Main.unity
git add Assets/Scenes/Main.unity

Emergency fallback: keep your version wholesale, then redo their changes by hand

Does this match your situation?

  • CONFLICT in a .unity, .prefab, .asset or .controller file.
  • The scene won't open after a merge, or Unity reports a corrupt scene.
  • GameObjects vanished or duplicated after merging.
  • Conflict markers appear inside a YAML file full of fileIDs and guids.

Step-by-step fix

  1. First, make sure your project is text-serialized

    Binary scenes cannot be merged at all. This is a project setting, and switching it is the single most important thing a Unity team can do for version control. Do it before you have a conflict, not during one.

    step 1
    # Unity: Edit > Project Settings > Editor
#   Asset Serialization Mode = Force Text
#   Version Control Mode      = Visible Meta Files

    Force Text converts scenes to YAML. Commit that conversion on its own, as one big commit, when nobody else has pending changes.

  2. Register Unity's smart merge tool with Git

    UnityYAMLMerge ships with the editor and understands scene structure — it merges by GameObject rather than by line, which is what makes a real merge possible. Point Git at it once per machine.

    step 2
    # ~/.gitconfig  (adjust the path to your Unity version)
[merge]
    tool = unityyamlmerge
[mergetool "unityyamlmerge"]
    trustExitCode = false
    cmd = '/Applications/Unity/Hub/Editor/2022.3.0f1/Unity.app/Contents/Tools/UnityYAMLMerge' merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED"
    Show the Windows path version
    Windows path
    [mergetool "unityyamlmerge"]
    trustExitCode = false
    cmd = 'C:/Program Files/Unity/Hub/Editor/2022.3.0f1/Editor/Data/Tools/UnityYAMLMerge.exe' merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED"

  3. Tell Git which files to route through it

    A committed .gitattributes applies for everyone who clones, so the whole team gets the behaviour automatically.

    step 3
    # .gitattributes
*.unity     merge=unityyamlmerge eol=lf
*.prefab    merge=unityyamlmerge eol=lf
*.asset     merge=unityyamlmerge eol=lf
*.controller merge=unityyamlmerge eol=lf
*.mat       merge=unityyamlmerge eol=lf

  4. Run the merge

    With that in place, resolving a scene conflict is the same as any other file — the tool does the structural work and only asks you about genuine overlaps.

    step 4
    git mergetool
# review the result IN UNITY before committing
git add Assets/Scenes/Main.unity
git merge --continue

    Always open the merged scene in Unity and check it before committing. A YAML merge can succeed textually and still be wrong.

  5. No smart merge available? Pick one side

    Hand-editing scene YAML is not realistic — the fileID cross-references are unforgiving. Take one version whole and redo the other person's work in the editor.

    step 5
    # keep yours:
git checkout --ours Assets/Scenes/Main.unity

# or take theirs:
git checkout --theirs Assets/Scenes/Main.unity

git add Assets/Scenes/Main.unity
git merge --continue

Why this works

A Unity scene is a graph of objects that reference each other by fileID. Git's default merge is line-based and has no idea those IDs are cross-references, so interleaving two sets of line changes can produce YAML that parses but describes a broken object graph — which is why scenes come back corrupted rather than obviously conflicted. UnityYAMLMerge parses the YAML and merges at the object level, preserving those references. Binary serialization removes even that option, since there are no lines to reason about at all.

If that didn’t work

  • Abort and split the work: git merge --abort, then have one person land their scene change first and the other rebase on top.
  • Extract large scene sections into prefabs so two people rarely touch the same file.
  • For studios versioning large binary assets constantly, Perforce or Unity Version Control handle exclusive file locking far better than Git.

How to stop it happening again

  • Turn on Force Text serialization and Visible Meta Files on day one.
  • Commit .gitattributes with the unityyamlmerge rules so the whole team inherits them.
  • Break scenes into prefabs so people work in separate files.
  • Agree who owns a scene for the day - social locking beats merge archaeology.
  • Use Git LFS for textures, audio and models so the repo stays workable.

Commands used in this guide

git mergetool

Open a visual three-way diff tool to resolve conflicts.

.gitattributes

Per-path rules for line endings, diffing, merging and export.

git merge

Combine another branch's history into the current one.

git lfs

Store large binary files outside history and keep the repo small.

git checkout

The old all-in-one: switch branches, restore files, or detach HEAD.

Still stuck?

Search the full command reference and every other rescue guide — there are 56 of them, covering everything from detached HEAD to force-push disasters.

Browse all guides →

Frequently asked questions

Can Unity scenes be merged in Git at all?

Yes, provided Asset Serialization is set to Force Text and you've configured UnityYAMLMerge as Git's merge tool for .unity and .prefab files. Without both, Git's line-based merge can silently corrupt the scene's object references.

Where is UnityYAMLMerge?

It ships inside the editor installation - Editor/Data/Tools/UnityYAMLMerge.exe on Windows, or Unity.app/Contents/Tools/UnityYAMLMerge on macOS. Point Git's mergetool config at the copy for the Unity version your project uses.

Should I use Git or Perforce for a Unity project?

Git is fine for most indie and small-team projects if you set up LFS and text serialization early. Larger studios versioning hundreds of gigabytes of binary assets, or needing exclusive file locking so two artists can't edit the same file, are genuinely better served by Perforce or Unity Version Control.

Why do .meta files keep conflicting?

Meta files carry each asset's guid and must be committed alongside the asset. Conflicts usually mean two people imported or moved the same asset independently. Keep one side's meta file, then let Unity reimport - never delete meta files to make a conflict go away, or references break project-wide.

Related rescue guides

Always fixable

Git says a binary file conflicts — how do I resolve it?

Binary files can't be merged line by line, so Git asks you to choose one version wholesale. Use git checkout --ours or --theirs to pick, then stage it. Mark such files as binary in .gitattributes so Git stops trying to diff them.

Read the fix →Always fixable

Git says I have merge conflicts — how do I fix them?

Git pauses and marks the clashing sections with <<<<<<<, ======= and >>>>>>>. Edit each file to the version you actually want, delete the markers, git add the file, then git merge --continue. If it gets overwhelming, git merge --abort returns you to exactly where you started.

Read the fix →Always fixable

I committed a large file and my push is rejected — how do I remove it?

If it's still the last commit, git reset --soft HEAD~1 and re-commit without it. If it's further back, purge it from history with git filter-repo --strip-blobs-bigger-than. Going forward, route large binaries through Git LFS.

Read the fix →Always fixable

Why is .gitignore not working for files that are already tracked?

.gitignore only applies to untracked files. Once a file has been committed, Git keeps tracking it no matter what the ignore rules say. Remove it from the index with git rm --cached <file> — that stops tracking while leaving the file on your disk.

Read the fix →
← All Git Rescue guides