How-To/Guide: Setting up MergeTools (UnityYAMLMerge.exe, etc) on a Mac for a Unity Project

[Gardenfiend Games]

Hey guys, there doesn't seem to be too much information on MergeTool settings for Macs (for Unity Projects) so I figured I'd make a super basic guide. This is just the information I've figured out from a couple emails between me and the Plastic guys - please feel free to add any more information, or correct me if anything is wrong. I am on a PC and have very little experience with OSX, but needed to configure this for a teammate's Mac. This guide is also meant for people coming from Unity Collaborate to Plastic SCM, who may not have any previous experience with source control. Also note that the 'code snippets' below are only a SECTION of the file - so do not copy/paste to replace your entire file - its best not to copy/paste anything from here into your own file.

What is Unity YAML Merge?

https://docs.unity3d.com/Manual/SmartMerge.html
UnityYAMLMerge is a merging tool that can be used on Scenes (.unity) and Prefabs (.prefab) to automatically handle the majority of merge-conflicts. TL;DR - this tool will let you open a scene and move around and change things on objects A, B, C, while your teammate also has that scene open and moves around and changes things on objects X, Y, Z. When you then go to push your changes to Plastic, there will be a conflict on that Scene file. By configuring Plastic to use this tool, it will analyze the changes made to that Scene, and so long as both team members didn't both change the same thing (like both team members moving object A), it will automatically combine the changes together. It's an incredibly useful tool.

How to configure MergeTools

There are two ways to manage your MergeTool settings. You can either go to Preferences -> MergeTools from within the Plastic client, or you can manually edit the client.conf file.

The client.conf file is located:
PC: c:/users/username/appdata/local/plastic4/client.conf
Mac: /Users/youruser/.plastic4/client.conf    Note: The .plastic4 is a hidden folder. To toggle visibility of hidden folders on Mac, press: [Command + Shift + . ]

 

If you use the migration tool to switch from Unity Collaborate over to Plastic SCM, then on Windows PCs, you will have a premade configuration that includes entries for scenes and prefabs to use the UnityYAMLMerge.exe tool. However, on Macs the MergeTools will only be set to the single default "$text" entry.

Here is what they look like (note that my windows client.conf has already had the UnityYAMLMerge.exe file location updated, as I'll discuss below):

WINDOWS - The Preferences -> Merge Tools window

WINDOWS - The <MergeTools> section of client.conf file:

<MergeTools>
    <MergeToolData>
      <FileExtensions>.doc;.docx</FileExtensions>
      <Tools>
        <string>"C:\Program Files\PlasticSCM5\client\diffscripts\merge-doc.exe" "@destinationfile" "@sourcefile"  "@output"</string>
      </Tools>
    </MergeToolData>
    <MergeToolData>
      <FileExtensions>.prefab;.unity</FileExtensions>
      <Tools>
        <string>"C:\Program Files\Unity\Hub\Editor\2020.2.0f1\Editor\Data\Tools\UnityYAMLMerge.exe" merge -p "@basefile" "@sourcefile" "@destinationfile" "@output"</string>
        <string>mergetool -b="@basefile" -bn="@basesymbolic" -bh="@basehash" -s="@sourcefile" -sn="@sourcesymbolic" -sh="@sourcehash" -d="@destinationfile" -dh="@destinationhash" -a -r="@output" -t="@filetype" -i="@comparationmethod" -e="@fileencoding" -m="@mergetype" -re="@resultencoding" --progress="@progress" --extrainfofile="@extrainfofile"</string>
      </Tools>
    </MergeToolData>
    <MergeToolData>
      <FileExtensions>.meta</FileExtensions>
      <Tools>
        <string>mergetool -b="@basefile" -bn="@basesymbolic" -bh="@basehash" -s="@sourcefile" -sn="@sourcesymbolic" -sh="@sourcehash" -d="@destinationfile" -dh="@destinationhash" -a -r="@output" -t="@filetype" -i="@comparationmethod" -e="@fileencoding" -m="@mergetype" -re="@resultencoding" --progress="@progress" --extrainfofile="@extrainfofile"</string>
      </Tools>
    </MergeToolData>
    <MergeToolData>
      <FileType>enTextFile</FileType>
      <FileExtensions>*</FileExtensions>
      <Tools>
        <string>mergetool -b="@basefile" -bn="@basesymbolic" -bh="@basehash" -s="@sourcefile" -sn="@sourcesymbolic" -sh="@sourcehash" -d="@destinationfile" -dh="@destinationhash" -a -r="@output" -t="@filetype" -i="@comparationmethod" -e="@fileencoding" -m="@mergetype" -re="@resultencoding" --progress="@progress" --extrainfofile="@extrainfofile"</string>
      </Tools>
    </MergeToolData>
    <MergeToolData>
      <FileType>enBinaryFile</FileType>
      <FileExtensions>*</FileExtensions>
      <Tools>
        <string>binmergetool -b="@basefile" -bn="@basesymbolic" -bh="@basehash" -s="@sourcefile" -sn="@sourcesymbolic" -sh="@sourcehash" -d="@destinationfile" -dh="@destinationhash" -a -r="@output" -m="@mergetype"</string>
      </Tools>
    </MergeToolData>
  </MergeTools>

ON MAC - the Preferences -> Merge Tools window

MAC - The ORIGINAL <MergeTools> section of the client.conf 

  <MergeTools>
    <MergeToolData>
      <FileType>enTextFile</FileType>
      <FileExtensions>*</FileExtensions>
      <Tools>
        <string>/usr/local/bin/macmergetool -b="@basefile" -bn="@basesymbolic" -bh="@basehash" -s="@sourcefile" -sn="@sourcesymbolic" -sh="@sourcehash" -d="@destinationfile" -dn="@destinationsymbolic" -dh="@destinationhash" -a -r="@output" -t="@filetype" -i="@comparationmethod" -e="@fileencoding" -m="@mergetype" -re="@resultencoding" --progress="@progress" --extrainfofile="@extrainfofile"</string>
      </Tools>
    </MergeToolData>
  </MergeTools>

 

My goal was to set up the Mac's merge tools to be as close as possible to the Window's ones - but there were certain ones that we didn't need, and there are some differences between what merge tools are available on the Mac versus the PC:

.doc; docx: We don't use this type of file in the project at all, so we didn't bother adding it to the Mac's merge tools list.

.prefab;.unity: This was the main goal - to get the UnityYAMLMerge.exe tool to work with these. I'll explain below how we added it.

.meta: I saw that on PC, the default "mergetool" was used for this. The equivalent on mac is the "macmergetool". This one was simple to add and we were able to do it in Preferences -> Merge Tools window. I believe all you have to do is click Add, choose Custom Extension and type in .meta, and then leave the Tool as the default - it basically filled this one in for us automatically. Sorry that I don't remember the exact steps, my teammate is the one with the Mac and he was screensharing when we set it up.

$text: This was already set up on the Mac.

$binary: I wasn't sure what this one did, so I asked the Plastic rep - He said that it is only available on Windows right now, and that it shows a diff between binary file specs and lets you choose which one to keep, the source, the base, or the destination - and that it's a really simple tool, for now. Since it isn't available on Mac, we didn't add it, and we haven't run into any issues. I am not sure if I've ever used it (or noticed using it) on the PC.

 

How to add the UnityYAMLMerge.exe merge tool on Mac
Ok, now to the important part - how to set up the YAML Merge tool. Here are the steps:

1) Locate the UnityYAMLMerge.exe tool:
PC: C:\Program Files\Unity\Hub\Editor\UNITY VERSION NUMBER\Editor\Data\Tools\UnityYAMLMerge.exe
Mac: /Applications/Unity/Unity.app/Contents/Tools/UnityYAMLMerge  Note: For those like me that are unfamiliar with Macs, the "Unity.app folder" does not look like a folder. It has the Unity logo kind of like an .exe would on Windows. I can't remember if you can double click on it to open the file, or if you have to Right-Click and do something else to open it.

Also note that the location on Unity's own website is outdated and incorrect: https://forum.plasticscm.com/topic/20639-unityyamlmergeexe-error-in-merge-tool/?do=findComment&comment=43710

2) In Plastic, go to the Preferences -> MergeTools window. We did two separate entries, one for .unity and one for .prefab. I believe you could do both as a single entry with semicolon separator (like this: .unity;.prefab) but we were trying to be careful and eliminate any possible issues. So for each one we clicked Add, then selected custom extension and typed in the .unity or .prefab, and then for External Tool we used Custom and browsed to the UnityYAMLMerge.exe tool location. I can't remember if this automatically added the "merge -p "@basefile" "@sourcefile" "@destinationfile" "@output"" part to the end of the entry or not. I think it did. If it doesn't for you, then you can manually add it, or manually edit the client.conf file to add it.

3) If you look at the Window's settings for .unity;.prefab, it says MULTIPLE_TOOLS, and when you look at the entry for it in the client.conf, it has two entries like <string> myEntry </string>. One is for the YAML Merge tool, and the other is the default "mergetool". Since we wanted to set things up on the Mac as similar as we could to the Windows version, we figured we would add the "macmergetool" as well for these filetypes. If I remember correctly, we first tried doing it by doing "Add..." in the Preferences -> MergeTools window, but I believe it showed up as a completely separate entry instead of saying MULTIPLE_TOOLS after adding it. So we decided to manually open the client.conf file, and add it in the same way as it appears in the Windows version (two <string> myEntry </string> entries back-to-back). We did it this way, and then restarted Plastic, didn't get any errors or anything, but when we went back to the Preferences -> MergeTools window, it only showed the YAML Merge tool instead of saying MULTIPLE_TOOLS. I'm not sure if this is just a GUI thing, or not. It might not matter at all. My guess is that the "mergetool"/"macmergetool" as the second entry would mean that it is only used if the YAML Merge tool isn't found. But I'm not sure. Maybe it handles the conflicts that the YAML Merge tool doesn't automatically merge.

The final <MergeTools> section for the Mac
 

 <MergeTools>
    <MergeToolData>
      <FileType>enTextFile</FileType>
      <FileExtensions>*</FileExtensions>
      <Tools>
        <string>/usr/local/bin/macmergetool -b="@basefile" -bn="@basesymbolic" -bh="@basehash" -s="@sourcefile" -sn="@sourcesymbolic" -sh="@sourcehash" -d="@destinationfile" -dn="@destinationsymbolic" -dh="@destinationhash" -a -r="@output" -t="@filetype" -i="@comparationmethod" -e="@fileencoding" -m="@mergetype" -re="@resultencoding" --progress="@progress" --extrainfofile="@extrainfofile"</string>
      </Tools>
    </MergeToolData>
    <MergeToolData>
      <FileType>enTextFile</FileType>
      <FileExtensions>.meta</FileExtensions>
      <Tools>
        <string>"/usr/local/bin/macmergetool" -b="@basefile" -bn="@basesymbolic" -bh="@basehash" -s="@sourcefile" -sn="@sourcesymbolic" -d="@destinationfile" -dn="@destinationsymbolic" -t="@filetype" -i="@comparationmethod" -e="@fileencoding" -sh="@sourcehash" -dh="@destinationhash" -r="@output" -a -m="@mergetype" -re="@resultencoding"</string>
      </Tools>
    </MergeToolData>
    <MergeToolData>
      <FileType>enTextFile</FileType>
      <FileExtensions>.prefab</FileExtensions>
      <Tools>
        <string>"/Applications/Unity/Hub/Editor/2020.2.0f1/Unity.app/Contents/Tools/UnityYAMLMerge" merge -p "@basefile" "@sourcefile" "@destinationfile" "@output"</string>
		<string>"/usr/local/bin/macmergetool" -b="@basefile" -bn="@basesymbolic" -bh="@basehash" -s="@sourcefile" -sn="@sourcesymbolic" -d="@destinationfile" -dn="@destinationsymbolic" -t="@filetype" -i="@comparationmethod" -e="@fileencoding" -sh="@sourcehash" -dh="@destinationhash" -r="@output" -a -m="@mergetype" -re="@resultencoding"</string>
      </Tools>
    </MergeToolData>
    <MergeToolData>
      <FileType>enTextFile</FileType>
      <FileExtensions>.unity</FileExtensions>
      <Tools>
        <string>"/Applications/Unity/Hub/Editor/2020.2.0f1/Unity.app/Contents/Tools/UnityYAMLMerge" merge -p "@basefile" "@sourcefile" "@destinationfile" "@output"</string>
		<string>"/usr/local/bin/macmergetool" -b="@basefile" -bn="@basesymbolic" -bh="@basehash" -s="@sourcefile" -sn="@sourcesymbolic" -d="@destinationfile" -dn="@destinationsymbolic" -t="@filetype" -i="@comparationmethod" -e="@fileencoding" -sh="@sourcehash" -dh="@destinationhash" -r="@output" -a -m="@mergetype" -re="@resultencoding"</string>
      </Tools>
    </MergeToolData>
  </MergeTools>

 

Another difference between Windows and Mac - the SemanticMerge tool:
Some info from my emails with the Plastic rep: The MacMergetool is the equivalent to the mergetool, but instead of having Semantic Merge 2.0, it has SM1, as it is the only one available for Mac. 

And when I asked about what the SemanticMerge tool is: SemanticMerge is a tool we provide that allows for code detection while running a merge. For example, if you have moved a method between controlled files, semantic should be able to identify those moves and notify you while diffing the content. 

Conclusion
All in all, the goal for us was to set up YAML Merge for the artist on my team who was using a Mac. He doesn't edit code or anything like that, so there may be some other specific things that you could set up if you were actually coding on the Mac. After setting all of this up, we tested the YAML Merge and so far it is working great - as far as we can tell there aren't any differences between how it looks/works on a PC versus how it looks/works on a Mac. If the merge can be automatic with no conflicts, it just goes through automatically. If there are conflicts, both the Mac and the PC open up the "three-way diff" window so you can handle the conflicts. I believe we did notice one difference where the PC had an extra dropdown menu option somewhere on the "three-way diff" window, so maybe that window is using the SemanticMerge? But overall they looked very similar.

If anyone has any information to add, or if I have any wrong information here please let me know. Hope this helps any of you coming from Unity Collab

 

[tahomasan]

Thanks for posting this. In my case I was missing the "default" macmerge tool associated with .meta extension. Cheers!