Distributed Version Control Systems (DVCS) are becoming a bread-and-butter everyday tool for software developers. An issue with Unity projects can be the many binary files in each project. There are also many files in a local system's Unity project directory that are not needed for archiving/sharing, such as OS specific thumbnail files, trash files, and so on. Finally, some Unity project folders themselves do not need to be archived, such as Temp and Library.
While Unity provides its own "Asset Server", many small game developers chose not to pay for this extra feature. Also, Git and Mercurial (the most common DVCSs) are free, and work with any set of documents that are to be maintained (programs in any programming language, text-files, and so on). So, it makes sense to learn how to work with a third-party, industry standard DVCS for the Unity projects. In fact, the documents for this very book were all archived and version-controlled using a private GitHub repository!
In this recipe, we will set up a Unity project for GIT DVCS through a combination of Unity Application settings and use of the GitHub GUI-client application.
Note
We created a real project this way—a pacman-style game, which you can explore and download/pull from the public GitHub's URL, available at https://github.com/dr-matt-smith/matt-mac-man.
This recipe can be used with any Unity project. In the 1362_10_09 folder, we have provided a Unity package of our matt-mac-man game, if you wish to use that one - in which case create a new 2D project in Unity, and import this package.
Since this recipe illustrates hosting code on GitHub, you'll need to create a (free) GitHub account at github.com if you do not already have one.
Before starting this recipe you need to have installed Git and the GitHub client application.
Learn how, and download the client from the following links:
To load the external resources by Unity Default Resources, do the following:
- In the root directory of your Unity project, add the following code into a file named
.gitignore(ensure that the filename starts with the dot):# =============== # # Unity generated # # =============== # Temp/ Library/ # ===================================== # # Visual Studio / MonoDevelop generated # # ===================================== # ExportedObj/ obj/ *.svd *.userprefs /*.csproj *.pidb *.suo /*.sln *.user *.unityproj *.booproj # ============ # # OS generated # # ============ # .DS_Store .DS_Store? ._* .Spotlight-V100 .Trashes ehthumbs.db Thumbs.db
- Open Editor Settings in the Inspector by navigating to Edit | Project Settings | Editor.
- In the Editor Settings, set the Version Control Mode to Visible Meta Files.
- In the Editor Settings, set the Asset Serialization Mode to Force Text.
- Save your project so that these new settings are stored. Then, close the Unity application.
- Log on to your GitHub account.
- On your GitHub home page, click on the green New button to start creating a new repository.
- Give your new repository a name (we chose matt-mac-man) and check the Initialize this repository with a README option.
- Startup your GitHub client application on your computer, and get a list of the repositories to clone to the local computer by navigating to File | Clone Repository ... From the list provided, select your new repository (for us, it was matt-mac-man) and click on the Clone button to this repository.
- You'll be asked where to store this repository on your local computer (we simply chose our Desktop). You will now see a folder with the repository name on your computer's disk, containing a hidden
.gitfolder, and a single file namedREADME.md.
- Now, copy to this local repository folder the following files and folders from your Unity project:
.gitignore/Assets/Library/ProjectSettings
- In your GitHub client application, you will now see lots of Uncommitted Changes. Type in a short comment for your first commit (we typed our standard—
v0.1 – first commit), and click on the Commit & Sync to push the contents of this Unity project folder up to your GitHub account repository.
- Now, if you visit your GitHub project page, you will see that all these Unity project files are available for download for people's computers either as a ZIP archive, or to be cloned using a Git client.
The special file called .gitngnore lists all the files and directories that are not to be archived.
Changing the Unity Editor Settings for Version Control Mode to Meta Files ensures that Unity stores the required housekeeping data for each asset in its associated meta file. Selecting Visible rather than Hidden simply avoids any confusion as to whether GIT will record the meta files or not—GIT will record them whether visible or not. So, by making them visible, it is obvious to the developers working with the files that they will be included.
Changing the Unity Editor Settings for Asset Serialization Mode to Force Text attempts to solve some of the difficulties of managing changes with the large binary files. Unity projects tend to have quite a few binary files, such as the .unity scene files, prefabs, and so on. There seems to be some debate about the best setting that should be used; we have found that Force Text works fine and so, we will use this at present. You'll see two commits on GitHub, since the very first was when we created the new repository, and the second was our first commit of the repository using the GitHub client, when we added all of our code into the local repository and pushed (committed) it to the remote server.
There are some details that you don't want to miss.
The following video link is a short introduction to DVCS:
Note that the Fogcreek Kiln "harmony" feature now allows seamless work between GIT and Mercurial with the same Kiln repository:
If you prefer to use Bitbucket and SourceTree with your Unity projects, you can find a good tutorial at the following URL:
While for many, using a GUI client, such as the GitHub application, is a gentler introduction to using DVCS, at some point, you'll want to learn more and get to grips with working in the command line.
Since both Git and Mercurial are open source, there are lots of great, free online resources available. The following are some good sources to get started on:
- Learn all about Git, download free GUI clients, and even get free online access to The Pro Git book (by Scott Chacon), available through Creative Commons license at the following URL:
- You will find an online interactive Git command line to practice in:
- The main Mercurial website, including free online access to the Mercurial: The Definitive Guide (by Bryan O'Sullivan) book is available through the Open Publication License at:
- SourceTree is a free Mercurial and Git GUI client, available at: