Using Version Control with Unity Free

With the recent release of Unity 4.2 the free edition has finally gotten the same version control features as the pro version (at least in regards to external version control, integration with the unity editor still requires Pro + a Team license). This post explains these what these features are, how they work and how to use them.

Anatomy of a Unity Project

Before I get into Unties version control features I’ll provide an overview the anatomy of a unity project.

  • Root: In addition to containing the folders described below the root directory of a unity project also contains the MonoDevelop/Visual Studio project/temp files. Unity generates these files for us automatically and so can generally be ignored by us.
  • Assets: The assets folder is where all your game assets are stored, including textures, materials, meshes, scripts, sounds, prefabs, scenes, etc.
  • ProjectSettings: This folder contains a series of text files corresponding to Unities project settings (Edit->Project Settings in the Editor).Library: contains metadata and cached data about the projects asset library. When you change the options of a game object or add a component in the inspector that information is stored here in binary format (at least in unities default configuration).
  • Temp: Used by unity to store Its temporary files. We can sadly ignore this directory.

Configuring Unity for Version Control

You can find Unity’s version control options under Editor -> Project Settings -> Editor. There are two options we want to change, Version Control Mode and Asset Serialization Mode. Set the Version Control Mode to “Meta Files” and the Asset Serialization Mode to “Forced Text”, as per the screenshot below:

Unity 4.2 Editor Settings
Unity 4.2 Editor Settings

Its worth noting that if you change these settings on an existing Unity project then Unity will automatically convert all the assets to use the new mode for saving data (see below), a process which can take hours for large projects.

Version Control Mode

This changes how Unity stores the meta-data for the game assets. Instead of using binary files in the Library Directory it saves a text file with each individual asset along side the actual asset file. For example if I had a prefab called “Ball.prefab” in the Assets\Prefabs folder then there would be “Ball.prefab.meta” file in the Assets\Prefabs folder as well. It is worth noting that all assets in the Assets folder get one of these *.meta file, including any sub folders you create.

Moving the asset meta data into the Assets directory in a text format allows us to add the folder to source control with support for merging changes made to assets using the inspector. However you’ll need to be carefull when moving or renaming Assets to move/Rename it’s *.meta file at the same time, otherwise Unity will get confused:

Unity *.meta File Error
Unity *.meta File Error

Another benefit of using the meta files is that Unity can use them to rebuild the Library directory when required. This means that we do not need to commit it to version control. Instead we can just let Unity recreate it for us when required:

Unity Library Rebuild Message
Unity Library Rebuild Message

This setting has actually been available in Unity Free since version 3.5.

Asset Serialization Mode

This setting changes how Unity saves things like Scenes and Prefabs. the “Force Text” setting tells unity to save them using its YAML format instead of its default binary format. This means that we can Merge/Diff these unity assets when required. However it also means that these file will be larger and take longer to load when we open the U editor, particularly Unity *.scene files.

One thing I’ll Mention here is that even though Unity’s YAML format can be merged, I’ve had trouble when there have been a large amount of changes, so its probable still worth avoiding have more than one person working on a Scene at any given time.

This setting has only just been made available in Unity Free with version 4.2.

Submitting to Version Control

After making the above changes in Unity submitting a unity project to Version control is fairly straight forward. Just add the Assets and  ProjectSettings Directory to you Version Control. Below shows an Example Unity Project Committed to Perforce:

Unity Commited to Perforce
Unity Committed to Perforce

If you’re using something like Git for you version control then you’ll want to ignore the Library and Temp directories, as well as the MonoDevelop project files in the root project folder.

Working with External Source Control

Having used Unity with Perforce for a while now I thought I’d share a few tips:

  • Unity has no respect for read only files. Unity will overwrite read only files automatically, without warning. This is a big problem when working with something like Perforce that makes use of the file system read only flag to control files. I recommend keeping track on exactly what files you modify as it is very easy to miss a modified file and not check it in.
  • Prefabs are saved when you save the scene. When I first started working in a team project checked into perforce we had a lot of issues where changes didn’t seem to be committed properly. It turns out this was because when you modify a prefab the changes are not written to disk immediately and won’t be until you save the scene. So save your scene before committing change, always.
  • Meta files don’t change very often. In my experience the only time you’ll need to check out meta files is when changing the import settings on an item, otherwise it remains unchanged for the life of a project (I’ve seen script files with 150+ version but only one version for the meta file).
  • A single change in Unity can effect multiple objects. For example if you change the shader on a material on a GameObject, then both the object and the material will be modified and need to be checked in.
  • Make everything a prefab. This makes it very easy for many people to work on the same scene at the same time. If everything is a prefab then you do not need to check out the scene, only the prefab you are modifying.
  • Unity handles external modification to assets well, but not perfectly. For the most part I have found that when getting the latest changes from source control Untiy will re-import the assets just fine without needing to be closed/restarted. On the rare occasion I had problems it was simple to fix, just close Unity and delete the Library folder. When you re-open unity it will re-import everything, unfortunately this takes a while on large projects.


So that’s how you use version control with Unity, not all that hard really.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s