Git and Unity

14 04 2015

Over the course of the last semester my capstone team has explored the use of Git revision control with Unity3D, both in theory and in practice. In this post I will outline the solutions we’ve come up with. The first part of this post examines the steps required to utilize Git reversion control with Unity3D. The second part outlines a work-flow for small teams based on feature-branching. At the end I will outline several potential pitfalls.

Setting Up Revision Control


Unity hides a great deal of meta-data for the asset files, so before we can set up the repository we first need to adjust some settings in Unity. For the following steps I assume you have already opened the project you wish to place under source control in Unity.

First we need to set the repository mode. If you are using Unity version 4.5 or later you can skip this step. Navigate to Unity → Preferences → Packages and setRepository to External.

Next we need to set the version control mode. This allows Git to see the meta files, so that it can track them. Navigate to Edit → Project Settings → Editor and setVersion Control Mode to Visible Meta Files.

Next we’ll set the asset serialization mode. Git does not handle binary files nearly as well as it does text (more on that later), so we’ll force it to use plain-text to store all assets. Navigate to Edit → Project Settings → Editor and set Asset Serialization Mode to Force Text.

Finally, save the scene and project to store the changes.


Now that we have Unity’s files prepared, we can set up the repository. There are two decisions to make at this stage: which client to use (if any) and which host to use (if any). We’ll start local, with the client, and shift to the host once we have the local repository initialized.

The Client

The first thing to do is decide on a client. I’ll leave this choice to the reader but I use SourceTree. Other popular options include the GitHub app and the git command line. Other tutorials exist for each of the aforementioned applications, so I won’t be going into detail here. Ensure you have a client installed before moving forwards.

Once we have a client ready we need to create the repository. The exact steps to do so vary based on the client, but all should execute the command git init. Do this in the root folder for your Unity project, the one with the Assets subfolder.

Before we commit any changes to the repository we’ll want to adjust the .gitignore file. The format of that file is beyond the scope of this document, but details can be found in the Git documentation. In particular, we want to prevent git from tracking the Library and Temp folders. We also want to ignore any .sln, .csproj,.unityproj, .orig, and .userprefs files. All of these are re-generated when Unity builds the project, and will show as updating for every commit if included.

Once the ignore file is updated we’re ready to make the first commit to the local repository. Do this using your client of choice, or the command line git commit.

The Server

If you’re working alone, and only from one machine you can skip this step, although I would advise maintaining a server repository as a backup regardless.

First you’ll need to decide where to host your repository. I use BitBucket, but GitHub and many other locations also offer free repository hosting. Alternatively, if you own a server of your own you can install Git there. Wherever you host, create an empty repository.

Make note of the repository URL, this is usually provided in a copy-paste box, and often ends with .git. Return to your client of choice, open your local repository (if you haven’t already), and add a new remote. (The command for this should be something like git remote add origin yoururl) While not mandatory, the primary remote is conventionally named origin.

First Push and Additional Contributers

Once you’ve set up your remote you’re ready to push the commit you made earlier. You’ll want to push to the remote repository you set up earlier, and to a new branch. (The command for this should be something like git push origin master) Again, while not mandatory, conventionally this main branch is named master.

Once you’ve made the push ensure the changes have appeared on the host you chose previously. If so, you’re ready to bring in any additional contributers for the project.

Each additional contributer should start by acquiring a client of their choosing. Ensure each additional contributer has a client installed before continuing, and give them all the URL for the remote repository.

Instead of creating a local repository they will be cloning the remote you set up earlier. How this is done will vary from client to client, but all should execute the command git clone yoururl. The code from the remote should be downloaded and a local repository created. At this point git and Unity are set up, and you can begin work on your project with whatever work-flow you may choose.

A Unity-Git Work-Flow


While having local and remote copies is, on its own, quite useful, perhaps the greatest value in using Git (or alternative source control systems) comes from the support for parallel work by multiple team members. For this to work smoothly, however, the team should decide on a work-flow in advance of beginning work on the project.

For the project which inspired this post I worked on a game in Unity with a team of two (2) other developers. Each of us had separate weekly milestones, with presentations every Monday with the combined changes. As such, we made heavy use of Git’s branching and merging features to allow each of us to make changes without interfering with the work of the others, and to merge as a group.


For the work-flow we settled on the master branch served as a release branch, with each commit representing a release-version of the software. While we didn’t do so, I would suggest using tags to label each commit with a release number.

Feature Branching Image

Because of the decision to use the master branch for releases no changes are permitted to be made directly to it. Instead every week we would each create a branch off of master named for the features we intended to add, or with a user-name and date. What you use is relatively unimportant so long as they can be kept distinct and consistent.

At the end of each week would sat down and worked together to merge all the changes back into master one at a time. As a result, we were all given the opportunity to examine each other’s code, offer suggestions for later improvements, and ensure everything fit together properly.

Caveats and Common Problems

As mentioned at the beginning of this post, Git doesn’t work as well with binary files as it does with text. Since it cannot identify changes, it will instead store a new copy of the file every time it changes. For large assets this can quickly eat though the space allotted for many free Git hosts. As such, it may be prudent to maintain a DropBox or other file-sharing solution in addition to the Git repository, and store any binary assets undergoing regular modifications there.

Additionally, while converting the meta-files to text helps Git keep track, they, and most asset files, are hard to read and modify by hand. As such, merging them can be an absolute nightmare. Our solution was to each maintain a separate scene for working in, then combine the changes by hand at the end of each week. The merged scene could then be copied into each individual scene to keep everything up to date.

Alternatively, there are several tools in the Unity store which propose to simplify the process with a graphical interface for merging such files. I have not had the opportunity to try them, but it may be worth the investment if a project is likely to be more asset heavy than code-heavy.

Finally, for teams new to Git ensure before each merge that everyone is certain of which branch is being merged into which; the interface for merging can be confusing, and it is easy to accidentally merge the master into a feature branch instead of vice-versa, and harder to fix it.




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

%d bloggers like this: