Saturday, 6 April 2013

Unity3D Version control with Dropbox and Mercurial

After a few months I think we're ready to share our Unity3D (free) version control setup. Keep in mind this is not ideal and it was designed to hack some sort of code tracking into the free version of Unity. We are using mercurial but there isn't (shouldn't be) any reason it wouldn't work with any other type of version control system. Always be aware you shouldn't have more than one person editing the files that are not on your VCS.

I'll assume everyone reading this has a basic knowledge on Mercurial and Aliasing/Symlinking and go straight to the point. If you need anything more specific feel free to comment and I'll consider adding it.

The concept:

There's 2 types of files in our project: binaries which we don't/can't synchronize (Unity Pro and the asset server solves this somewhat) and code (text) files. We don't want to do version control for binary files. Let's begin by putting all our binary files into a separate folder. This is what our project's hierarchy looks like:



First thing's first, launch your project and go to Edit->Project Settings-> Editor. In the inspector change the version control mode to meta files and Asset Serialization to Mixed mode. This means from now on all the data on your Prefabs, materials, scripts, etc will be store in .meta files in their respective folder instead of clumped up in the Library folder.

Basically we just shove everything that's not a text file into the Binaries folder. Close unity, take this folder and put it's contents into a Dropbox folder (we'll be using "\Titan Forged Games\Brian Storm\Unity Project\Assets\Binaries").

Create the repository. This is the contents our .hgignore file (aka the files and folders our repository should ignore):

syntax: glob






The Library folder should never be synced. Doing so is a recipe for disaster. It has local data regarding the project and will always be regenerated based on the .meta files. The library folder will ALWAYS be unique for every person so DON'T even try to sync it and always make sure it's not being shared (we almost lost an entire project due to a silly mistake with the Library folder being corrupted on a single machine).

The rest of the list exists mostly to keep useless binary data or personal preferences from our repository. The .orig are files generated by mercurial if you wish to store backups of files before a merge operation - feel free to ignore that line (it's just personal preference).


How to use it:

Clone the repository.
Create a symlink (or shortcut) for the binary files in the Dropbox folder.

In our most current project we're using the dropbox folder "Titan Forged Games\Brian Storm\Unity Project\Assets\Binaries" to "place" binaries into our repo's "Assets\Binaries"

On windows 7 (and 8) you can launch the command console and type: mklink /J "YOUR REPO PATH\Assets\Binaries" "C:\Users\YOUR NAME\Dropbox\Titan Forged Games\Brian Storm\Unity Project\Assets\Binaries"

From now on, everything that is on "C:\Users\YOUR NAME\Dropbox\Titan Forged Games\Brian Storm\Unity Project\Assets\Binaries" will be identical to
"YOUR REPO PATH\Assets\Binaries"


  • Don't ignore the newly created .meta files when commiting a new code file. They are what allows Unity to know if your GameObjects use a certain script (otherwise you'll just get missing script Errors on GameObjects that use them).
  • When testing things out and doing drastic changes it's best to avoid people tweaking an editor scene (besides not being able to work on the same scene at the same time, it's also likely he's messing with inspector attributes that will no longer exist once you commit your code).
  • The silly mistake I mentioned earlier deleted all our binaries on the dropbox folder. Don't be silly and do regular backups of the Binaries - in fact, just backup your entire project once in a while, you'll be thankful for it some day.