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.

Introduction

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.

Meta Files

It is important to understand the need for Meta Files when wor　　king 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).

TestScene.unitypackage.

With Unity open, go to Edit > Project Settings > Editor.

Unity – Enable Meta Files

You will notice that the Inspector panel turns into Editor Settings.

Select the Meta Files option for the Mode setting under Version Control.

Unity – Enable Meta Files

After enabling this option, you should see a .meta file for every file and folder in your Unity project’s Asset folder.

Meta Files

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.

Checkout

Before you can add your files to the repository, you need to perform a checkoutoperation (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.

SVN Checkout

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.

SVN Checkout Dialog

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.

TortoiseSVN Warning

You should be presented with a confirmation dialog stating that the checkout operation completed.

Checkout Confirmation

Adding Files

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:

Assets
ProjectSettings

DON’T ADD THESE FILES

The following folders should NOT be added to version control:

Library
Temp

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).

Ignore Files

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).

SVN Ignore Folders

Once a file or folder has been ignored, it won’t show up in the commit dialog anymore.

Commit Changes

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.

SVN Commit

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!)

Commit Changes

Click OK to confirm you want to commit the changes to the repository. If everything was okay, you should see the following dialog box:

Commit Finished

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.

When moving asset files or folders in a Unity project folder, always move/rename the corresponding .meta file! Not doing this will break the references to those assets in all of your scene files!

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.

Copying Files

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.

Conclusion

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.

Exercise

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.

4 THOUGHTS ON “USING VERSION CONTROL WITH UNITY”

Sigmund on September 15, 2013 at 3:21 pm said:

Here’s another good suggestion for using version control with Unity.

As of Unity 4.2, they’ve made the option for text serialization of assets available to all users, not just Pro. After doing this, all asset files that were previously saved in binary format are saved in a completely readable YAML representation in a text file. Changes to scene files can actually be read, and merged if you’re careful. Very useful if you have multiple people working in a project.

Reply ↓
- Jeremiah van Oostenon September 17, 2013 at 8:33 pm said:
  
  Sigmund,
  
  Thanks for this great tip. But be careful, large scene files with many gameobjects will still be difficult or impossible to merge correctly if you not very careful.
  
  A better solution is to split level design into separate scene files and use Application.LoadLevelAdditive to combine several levels into one at runtime.
  
  The best solution would be to have this concept “Additive” level design integrated into unity. UDK does this with Persistent and Streamed levels ()
  
  Reply ↓
Chufraise on January 4, 2014 at 1:34 am said:

Hi Jeremiah,
Great article, thanks! I’m having some troubles tho when checking out a project without a Library folder. All prefab and script link are broken, which means something is broken in the meta data. I’ve done everything according to the best practises before importing the project in the first place, such as enabling visible meta files. I initially imported the Assets- and the ProjectSettings folders, but when checking the project out on another computer everything’s screwed up. When checking out the original Library folder everything works fine. Do you possibly have an idea on what I’ve done wrong? I’m using Unity Free 4.3. Thanks!

Reply ↓
- Jeremiah van Oostenon January 6, 2014 at 3:52 pm said:
  
  If meta files are regenerated then the references to those assets will be broken. Make sure that when you put files in the Assets folder that they have corresponding meta files and the contents of the files should not be changed after Unity imports those files (the UUID’s should not change).
  
  The best thing to do is to use the Import Package function in Unity to import assets created in another Unity project. Doing this will maintain references to assets within the package.
  
  Reply ↓

Unity使用外部版本控制SVN

Using External Version Control Systems with Unity

Example: Creating a new project and importing it to a Subversion repository.

Table of Contents

Introduction

Meta Files

Enable Meta Files

Working with Version Control

Checkout

Adding Files

DO ADD THESE FILES

DON’T ADD THESE FILES

Ignore Files

Commit Changes

Moving and Renaming Files (Very Important)

Copying Files

Conclusion

Exercise

4 THOUGHTS ON “USING VERSION CONTROL WITH UNITY”