When working on Unity HoloLens-projects in teams, sometimes merge conflicts in Unity scenes are unavoidable. Even though the Unity scene file format is text-based, the automatic merge of a standard GIT merge tool wouldn’t always correctly recognize the changes from different versions.
Luckily, Unity comes with a merging tool that is specialized on scene files: UnityYAMLMerge / Smart Merge. However, it’s not straight-forward to integrate into a workflow.
If not working in specialized environments (e.g., with Visual Studio), I frequently use TortoiseGit for Windows. The quick GIT status overview in Explorer, as well as the easy routine interactions with GIT are efficient to use for projects.
Integrating UnityYAMLMerge with TortoiseGit
The official instructions from Unity explain how to tell TortoiseGit to use the Smart Merge tool from Unity for .unity (scene) files: go to TortoiseGit Settings > Diff Viewer > Merge Tool > Advanced. In this dialog, click on “Add…” and then add the following for the .unity file extension (of course, replace the directory with your local system config if necessary):
C:\Program Files\Unity\Editor\Data\Tools\UnityYAMLMerge.exe merge -p %base %theirs %mine %merged
However, this doesn’t yet fully work. In case UnityYAMLMerge doesn’t succeed automatically, it still requires manual intervention and needs to open a merge tool that allows user control.
The merging itself will fail with the following reason:
Auto-merging Assets/MainScene.unity CONFLICT (content): Merge conflict in Assets/MainScene.unity
If you then attempt to start the Resolve process, you will get the following error message from UnityYAMLMerge:
UnityYAMLMerge - Couldn't locate merge tool to handle extension tmp
Default Fallback File
Apparently, the UnityYAMLMerge tool doesn’t find a tool to let the user resolve the conflicts for the .tmp files it creates. The Unity manual reveals that the tool uses a default fallback file (mergespecfile.txt ), in the same folder as the tool itself:
C:\Program Files\Unity\Editor\Data\Tools\UnityYAMLMerge.exe
This fallback file includes some command line statements for a few common merge tools – but not for TortoiseGitMerge. I couldn’t find instructions on which parameters to use.
Therefore, I read the documentations of TortoiseGitMerge and built the correct interface between these two tools.
To make it work, add the following lines after line 22 into the file. This will launch the external tool if Unity’s Smart Merge needs to do so.
# Tortoise Git Merge * use "%programs%\TortoiseGit\bin\TortoiseGitMerge.exe" -base:"%b" -mine:"%l" -theirs:"%r" -merged:"%d"
If you try again now, UnityYAMLMerge can correctly launch TortoiseGitMerge for the remaining conflict between the different branches:
To resolve the conflicts: right-click on the lines and choose what version you want to use, then save and close the window. You won’t see a success message, but the scene file has now been merged. At this state, you will still have several different versions of your Unity scene in the folder: the merged version + base, remote and local versions.
Check if the main scene file looks ok. Open the project in Unity to see if everything still works. Then, resolve the merge by accepting the new scene file. Commit and push the changes, and you’re done.