As part our team project, we are creating a game so therefore we need some way to all have access to the latest code and art. Thus we decided to use Git as it’s pretty much the industry standard and fantastic. However unfortunately by default Unity and Git don’t really play well together (as I learned from spending easily 2+ hours resolving merge conflicts and still having issues). Thankfully, Unity release a tool with Unity 5 called UnityYAMLMerge to help with these situations. You can read more about it here if you’re interested.
Anyway getting Git and the tool to work was fairly easy, it just requires some editing of files but can be quite confusing for users new to Git. Hence writing this guide! Hopefully you’ll find it useful but leave a comment if you run into any issues and I’ll try to help 🙂
What this guide will not do
- Teach you how to use Git
- How to resolve merge conflicts in general (only how to make them not break your Unity scenes/prefabs)
This also assumes you have already setup a basic Git repository.
Setup .gitignore file
Having a .gitignore file means that Git will ignore certain files and folders which is useful in this situation as we don’t need to commit everything Unity generates, saving both space and time.
- Download the .gitignore file (See here for non download version)
- Place the file in the root project directory
Git treat certain files as binary files
This is an important step to prevent Git from trying to auto resolve merge conflicts which can break scenes most often.
- Download the .gitattributes file (See here for non download version)
- Place the file in the root project directory
Setup Unity to save scenes in text
- In Unity, go to Edit -> Project Settings -> Editor
- Set Version Control -> Mode to Visible Meta Files
- Set Asset Serialization -> Mode to Force Text
Setting up UnityYAMLMerge
This part is the tricky part as it will require a few file tweaks. It will also vary depending upon the merge and diff tool you prefer as well as the way you interact with Git (Whether via command line or a GUI such as SourceTree)
For the purpose of this guide, I will use KDiff3 however you can set up UnityYAMLMerge to use your preferred tool (and it has some as default configurations for some tools)
Unity has a manual entry here however some information is incorrect (such as setting up in the .gitconfig file). The first part of the guide is also not neeed
Setup fallback merge tool
This is an important step and allows you to still resolve normal conflicts as well as resolve scene and prefab conflicts after UnityYAMLMerge fixes them.
- Go to <Unity Install Directory>\Editor\Data\Tools
- Open up mergespecfile.txt
- Read the first few lines so you understand what it is for
- If you use one of the programs already listed in the file, you’re done in this section
- If you want to use KDiff3, follow this section. Otherwise, skip to 5
- Replace the “unity use” and “prefab use” lines with the ones below
- unity use “%programs%/KDiff3/kdiff3.exe” “%b” “%l” “%r” -o “%d”
- prefab use “%programs%/KDiff3/kdiff3.exe” “%b” “%l” “%r” -o “%d”
- Under “Default fallbacks for unknown files. First tool found is used.” paste the following
- * use “%programs%/KDiff3/kdiff3.exe” “%b” “%l” “%r” -o “%d”
- Follow the instructions listed at the start of the file to use your preferred editor. You may also need to refer to the editors documentation
Setup Git to use UnityYAMLMerge
Now that UnityYAMLMerge is setup, we need to tell Git to use it for resolving conflicts. This again heavily depends upon how you interact with Git so your experience may vary.
- Check here first to see if there is a way already listed on setting it up (Ignore the Git section). If it’s listed, follow the instructions and you’re done!
- If you wish to use command line Git or another tool, read the rest of this section.
- Go to your user home directory (For windows, this is C:/Users/<username>/)
- Open the .gitconfig file with a text editor
- Paste the following at the end of the file, replacing the sections in <>
You’re all setup and ready to go now! Try merging two different versions of scenes and see what happens. What you’ll find UnityYAMLMerge does is try to automatically merge them as much as possible (including component deletion/additions) but not on the variables. This will use your fallback merger that was setup earlier and that works the same way as your usual merge, thus preventing scenes from completely breaking.
Scenes may still break, this tool tries its best but it’s not always perfect. Avoid large merge conflicts by merging together every now and then (don’t let it go weeks) to reduce the chance of anything exploding.
Git files (Non Download)
The .git* files can viewed as part of this gist in case you don’t want to download them.