In this article, I will briefly describe how to setup a Unity project together with a Version Control System (VCS). I will show you how you can setup a Unity project to work with Subversion (SVN) but the method to use Unity with other version control systems should be similar.
Table of Contents
Unity is a game development tool that allows you to create great games and deploy them to almost any platform you can imagine. Unity provides a great asset handling pipeline. Most of your game assets (like models, textures, audio files, and scripts) are automatically built for the platform for which they are to be used.
Although Unity is a great platform for creating games, historically it has not always been very easy to work in large teams with Unity. Unity has traditionally encouraged developers to use the Unity Asset Server for managing the Unity project across large teams. And although the Unity Asset Server is a good solution for working in large teams, it does incur additional licensing costs that may not be practical for smaller teams.
The developers at Unity recognized that their users wanted to integrate their Unity projects into their existing version control systems so they provided the ability to work with meta files which are used to keep track of the different assets in the project. By enabling these meta files, you can now work with version control systems like Subversion and Git in large teams and across different platforms without losing the references to your assets.
It is important to understand the need for Meta Files when working with a Version Control System. When you reference a game asset in a scene, Unity does not use the name and location and name of an asset internally, instead Unity uses a Globally Unique Identifier (GUID) to uniquely refer to an asset in your project. This GUID is stored in a meta file that is created for each folder and each asset in your Unity project’s Asset folder.
The use of GUIDs has its advantages but it also has its disadvantages. The advantage of using GUIDs is that you can move or rename or modify the contents of an asset and the asset can still be referenced by its GUID (as long as the GUID stays the same, the asset can be referenced). The disadvantage is that you must be aware of the presence of the meta file that is associated to a particular asset. If you delete the meta file that is associated with a particular asset, Unity will think the original asset has been deleted a new GUID is generated and associated to that asset. This is the most common reason why references to assets will suddenly break in your scene file.
In addition to the GUID, the meta files store information about the asset that is used to re-import it. For example, texture assets can be configured to be imported as a standard texture, a normal map, a GUI texture, a cookie, texture, or a lightmap texture. These import settings are also stored in the meta file.
Enable Meta Files
By default, meta files are not enabled for new projects. You must explicitly enable meta files for each new Unity project you want to manage with version control.
To do this, open your Unity project in the Unity game editor. If you don’t yet have a project, download the unityproject file below and import it into an empty Unity project (It’s just a crate, but it’s enough to use as an example).
With Unity open, go to Edit > Project Settings > Editor.
You will notice that the Inspector panel turns into Editor Settings.
Select the Meta Files option for the Mode setting under Version Control.
After enabling this option, you should see a .meta file for every file and folder in your Unity project’s Asset folder.
Working with Version Control
At this point, I assume you have access to a version control repository somewhere. Setting up a repository is beyond the scope of this article so I will not explain that here.
I will show how to work with Subversion using the TortoiseSVN client on Windows. Working with other version control systems will be similar but the steps to manage your repository may be different.
Before you can add your files to the repository, you need to perform a checkout operation (if you haven’t already done so). If you already have a working copy where you want to put your Unity project, then you can skip this step.
Navigate to the directory where you created your Unity project.
Right-click on the project root folder (the folder that contains the Assets folder) and select “SVN Checkout…” from the pop-up menu that appear.
Specify the URL of the Subversion repository and the directory where you want to create the working copy (this should be the root of your Unity project folder) and press OK to perform the checkout operation.
The TortoiseSVN client should display a warning dialog box stating that the directory is not empty. Confirm that you want to checkout to this folder by clicking the Yes button.
You should be presented with a confirmation dialog stating that the checkout operation completed.
Now that we’ve created a working of the SVN repository, we can add the necessary files to it.
Not all of the files in the Unity project folder should be added to the repository.
Do Add These Files
Only two folder (and all of their contents) should be added to the repository:
Don’t Add these Files
The following folders should NOT be added to version control:
Also, all of the files that Unity generates in the root folder of the Unity project folder should not be added to version control (because these can be regenerated by selecting Assets > Sync MonoDevelop Project from the main menu in the Unity editor).
It is highly recommended that you tell subversion to always ignore the files and directories that you do not need to add to version control. To do this, right-click on the files/folders that you do not want to add to version control and select TortoiseSVN > Add to ignore list > Ignore items by name (or ignore by extension if you want to ignore all files with a particular extension).
Once a file or folder has been ignored, it won’t show up in the commit dialog anymore.
Once the necessary files have been added to the working copy and the Library, Temp, and other files have been marked as ignore, we need to commit the changes to the SVN repository.
Do do that, right-click on the root folder of the Unity project and select SVN Commit… from the pop-up menu that appears.
You should be presented with a commit dialog box. Enter a message that describes the changes you are committing and confirm that all of the files and folders that should be added to the repository are checked (including the .meta files!)
Click OK to confirm you want to commit the changes to the repository. If everything was okay, you should see the following dialog box:
Moving and Renaming Files (Very Important)
If you have read the standard Unity documentation, you may have noticed that the guys at Unity recommend that you never use Windows Explorer (or Finder on OS X) to move or rename files that are in your Unity project’s Asset folder. They recommend that you only use the Project View in the Unity editor. This is true if you are using the Unity Asset Server or not using version control at all. However, if you are using a version control system (like Subversion) then you MUST use the SVN client (in the case of Windows, this is usually TortoiseSVN) to move or rename files that are part of an SVN working copy. The most important thing to remember is that if you move a file or folder that you also move/rename the corresponding .meta file that is associated with that folder or asset.
If you don’t move/rename the corresponding .meta file for a folder or an asset in a Unity project’s Asset folder you will break the reference to that asset in every scene file it is used.
BE VERY CAREFUL WHEN MOVING/RENAMING FILES IN YOUR UNITY PROJECT!
If you accidently move/rename files in the Project View in the Unity editor, you will break the link to the file as known by the Subversion system. To resolve this, move/rename the file/folder back to it’s original name in the Project View and perform the move/rename using the SVN client instead. Make sure you also move/rename the corresponding .meta file that is associated with the file/folder you are moving/renaming.
If you want to make a copy an asset, do not copy the .meta file with it. The .meta file contains the GUID for that asset and if you make a copy of the .meta file, Unity will not longer know which is the correct asset for the GUID.
In this article, I showed you how to add your Unity project to a version control system. The most important thing to remember is to always enable Meta Files when working with a version control system such as Subversion. Failing to do this, or not committing the .meta files with the corresponding assets will break the references to those assets in the scene files.
Don’t commit the Library and the Temp folder to the version control system because Unity will automatically create these folders if they don’t already exist. You should also not commit the solution files and project files that are automatically generated by Unity when you select Assets > Sync MonoDevelop Project from the main menu in the Unity editor. These files get overwritten when Unity regenerates them and they don’t need to be put in version control.
Practice this own your own or with your team. Make sure that you can perform a fresh checkout of your project in a new folder or on a teammates computer and confirm that all of the references to assets in the scene files are correct.
If you have turned on Meta Files, you should be able to delete the Library folder in the root of your Unity project and Unity should correctly recreate the Library files and restore all the references to the assets in the scene files.