Note: The really interesting bit is at the end of the article. So if you don't stick around for the whole journey, at least skip to the end! That being said, this is all useful stuff so you should, yeknow, stick around...
Unity is a pretty solid game engine that at least a few people are using, but it doesn't play very nicely with Git - my preferred source control mechanism - by default. While I can't speak for everyone, there are three major issues I've always wanted to address:
- The default setup all but guarantees that having two different users push the same scene, prefab, ScriptableObject, etc will render it totally unusable and force you to rollback (quite painfully) to an old version.
- Git, by design, doesn't play very nicely with binary data. It's diffing tool doesn't support binary files and, as such, it stores the entirety of each revision of binary files for every commit. As a lot of game content is stored as binary data - FBX files, textures, etc - this presents a bit of a problem for storage.
- After playing with Unity Collaborate a bit, it became extremely evident that the UI/UX for interaction between traditional source control and the Unity editor could be drastically improved.
In the past we've sort of just worked around these issues, but I spent a fair amount of time recently figuring out how to address all of these issues more directly. With some additional configuration steps and a little bit of editor scripting, all of these issues can be addressed quite nicely.
Unity's SmartMerge
YamlSmartMerge is a feature included in Unity 5+ that allows you to safely merge changes to prefabs and scene files, addressing issue 1. I believe it is what Unity Collaborate uses internally, but have nothing other than my own observations to back up that claim.
When it works, it is fantastic. Person A can tweak component values on objects X, Y, and Z while Person B is building out the level, then Git merges the changes with only a little bit of coaxing (you have to manually merge from the command line, or write an editor script to do it - more on that in a bit).
However, it isn't always that easy. Inevitably, you'll run into a scenario where Person A and B modify the same object. Unity seems to solve this by picking either Person A or B's changes and silently clobbering the other person's. This is understandable behavior, but without telling the user exactly what changes were clobbered, this solution suddenly looks a whole lot worse. That being said, it is definitely better than the alternative wherein assets are simply left unusable, and the manual intervention generally lets the user know when they should be careful.
The Unity documentation has partial instructions on how to get SmartMerge working with git, but I tend to refer people to this guide which is considerably more detailed and goes into a few things the docs miss. That being said, the setup must be done for each collaborator and is a bit overcomplicated in my opinion, especially for collaborators who aren't quite as technically inclined.
While I believe all Unity projects using git should really be using this, given its drawbacks (which, for me, mostly involve its perceived unreliability), I don't believe this to be a complete solution by itself. Furthermore, it does nothing to address issues 2 or 3.
Git LFS
LFS is an extension to git which is primarily meant for storing large binary files outside of your main repository. It is fairly easy to install and configure for GitHub, though I can't speak for the other major git providers (I believe GitLab's support is only partial and I'm not sure about BitBucket). This solves issue 2.
For configuration reference, this is the .gitattributes for my current project:
*.unity binary lockable *.prefab binary lockable *.asset binary lockable *.fbx filter=lfs diff=lfs merge=lfs -text lockable *.png filter=lfs diff=lfs merge=lfs -text lockable *.tga filter=lfs diff=lfs merge=lfs -text lockable *.psd filter=lfs diff=lfs merge=lfs -text lockable
LFS also implements an incredibly useful feature sorely missing from git - file locking. As the name implies, file locking prevents other users from committing files you have explicitly locked. This locking prevents issue 1 from occurring altogether, though in my opinion, it is best to combine this with YamlSmartMerge in case you know two users will be editing specific parts of the scene.
The major drawback of LFS locking is that it doesn't actually prevent the local user from writing to the file, or even from committing- just from pushing it. So by itself, this can be a bit confusing as there's no built-in way to visualize locks or physically lock the files.
LFS and SmartMerge can therefore handily solve problem 2 and partially solve problem 1. However, neither touches issue 3. If only Unity had an extensible editor... Oh wait, it does!
Integrating with the Unity Editor
As mentioned earlier, I really liked parts of Collaborate's integration into the Unity editor. Specifically, I really liked the ability to see who was working on a file at any given time. Unfortunately, we had some major issues with Collaborate that made it essentially unusable in the project I'm currently working on, so we had to switch to git mid-production.
Because some of the team members were very used to the ease-of-use of collaborate (and because I liked the editor stuff so much), I wrote an editor plugin that adds most of the features that I liked in collaborate into the editor for Git, as well as a host of additional features. I could explain the major ideas behind it, but it'd be easiest just to show them.
By default, saving a scene will automatically lock it. This can be toggled in the settings, but it's very useful to prevent accidental merge conflicts. Even though smart merge can theoretically save you if that happens, I don't trust it enough to try.
The plugin tells you (via a tooltip) who owns any active lock so you know exactly who to yell at if you need to change a locked scene. By default, it also actually locks files for writing if someone else owns the lock. This way there's absolutely no chance that two people will be working in and saving a scene at the same time.
Furthermore, the plugin provides an abstract interface so that you can write a backend for whatever VCS you want. It's a pretty nifty little framework, if I do say so myself.
Check out the GitHub repository if you'd like and, by all means, please contribute. It isn't perfect and, as my current project progresses, it'll undoubtedly mature and evolve, but it's pretty neat for a first revision and definitely fills a gap that it seems Unity has really always had. So hopefully you find it useful, or at least interesting.
Until next time...