Featured Blog | This community-written post highlights the best of what the game industry has to offer. Read more like it on the Game Developer Blogs or learn how to Submit Your Own Blog Post
This tutorial takes you through the steps to start using Git with Unity.
[If you have any feedback or questions on this tutorial please let me know @doolwind]
We’ve started using Git for our Unity3D projects and this tutorial describes the best way to set up a Unity3D project to use Git for source control as well as some best practices. In the past we’ve used SVN and Mercurial as well and so far we’ve found Git to be the best option. The main advantages of using Git with Unity are:
Support for Unity Cloud Build
Distributed development allowing offline work when on the road or otherwise disconnected from the internet
A number of GUI clients
Cross platform support
The main disadvantages of Git are:
Not specifically supported by Unity, however it works without an issue
Not great for large files
Can be complex for some team members
I’ll just jump straight into the steps for getting yourself set up with Git. You have two options for creating a Git account, GitHub and BitBucket. For a more comprehensive tutorial on the git commands, check out the Git tutorial. This tutorial will use BitBucket as you can create a free private repository, however everything after the first 2 steps are the same if you use GitHub.
Getting Started
Create a BitBucket account if you don’t have one - https://bitbucket.org/
Create a new repository on BitBucket
After signing up you are automatically taken to the create repository screen. If you missed this, you can just click the “Create” button at any time within the BitBucket header to create a new repository
Choose “Empty” repository and give it a name
You will be prompted to download SourceTree or to Install Git. For this tutorial will will use the command line version of Git, SourceTree is a great option if you don’t like using the command line
Set up your local directory
Drop into a command window on your platform (I use powershell on Windows)
Create a new directory for your project (mkdir /path/to/your/project)
Go to the new directory (cd /path/to/your/project)
Initialize git (git init)
Add the new remote repository (git remote add origin https://<username>@bitbucket.org/<projectname>/<projectname>.git)
This copies the remote repository (sitting on bitbucket) down to your local machine
From here you make changes to the source and push back up to the server once finished
Create a new Unity project in the project directory
Set up your Unity project to work with Git (or any source control)
Navigate to Edit -> Project Settings -> Editor
Change Version Control Mode to Visible Meta Files
Change Asset Serialization Mode to Force Text
Save the current scene of your game
Close Unity
Update your gitignore_global.txt file to ignore unwanted Unity files
Unity has a bunch of files we don’t want to check into source control. Copy the lines from the following file into your gitignore_global.txt file to ignore these unwated files.
The only directories you need to have source controlled for a Unity project are Assets and ProjectSettings. Unity has done a great job of separating all the temporary files out into their own directories.
The global ignore file is used across all git projects and saves you ignoring the same files each time you start a new Unity project. This file is combined with project specific ignore files (see below) to determine the full ignore list
Add the new files to your local repository (git add .)
The period (.) at the end of the line adds all files
This tells git you want to include the added files in the commit
Check that the files have been successfully added (git status)
You should see about 16 files
If you see more, check that you have set up you gitignore_global.txt file correctly
Commit the changes to your local repository (git commit -m “Initial Commit with empty project”)
The -m switch lets you supply a message to your commit. These should be clear and concise
The changes are now committed to your local repository, next we will push them up to the server
These changes are not yet up on the server
Push the changes to the BitBucket server (git push -u origin master)
Enter your password
The -u origin master parameters let bitbucket know where to push these changes. From now on you will only need to call git push to push changes
This pushes your local repository (that you commited in step 11) up to the server. Note that any changes in your working directory will not be pushed to the server
You’re now set up with Git for your Unity project. Below is an overview of the different parts of git:
Working directory - this is your local file system containing your Unity files. This is basically your src tree as it was before source control (with a hidden .git directory that stores all of the git related stuff, Unity ignores this folder)
Local repository - Think of this as a local copy of the source tree with all the changes that have ever been made to the project. This resides on your local PC and can be committed to independently of the server repository
Server repository - This is the server copy of the source tree that is shared between all the users of the project. Changes from each developer are pushed up from their local repository into this shared repository (that sits on BitBucket in this example but can be anywhere).
Below are common commands you will use
To pull changes from other team members
git pull
To commit further changes
git commit -m “<your message>”
To push more changes to the server
git push
To see which files are in your working copy (which files have changed locally that have not been commited)
git status
To add new files to a commit
git add .
To add a specific file to a commit
git add <filename>
To ignore project specific files
Create a .gitignore file (touch .gitignore)
Add the files to be ignored to .gitignore
Add .gitignore to the commit (git add .gitignore)
View changes made in the working directory (git diff)
I highly recommend a tool like Araxis Merge or similar for powerful diff and merging
Revert local to latest commit (git checkout -- .)
If you’re working and decide you want to revert the work you’ve done to the previous commit
Make sure you remember to period (.) at the end
Not this won’t remove added files, it simply reverts modifications (and deletions) to the previous commit
For more commands I highly recommend the git tutorial
Some thoughts on workflow
One of the only major downsides to Git (or any distributed source control) is the inability to lock files so multiple users can’t edit them at the same time. Unity’s “force text” option minimizes these problems, however there can still be conflicts if you have multiple poeple working on the same files, especially .scene files. There are a few options to get around this:
Only have one person working on a particular scene file at a time
Use prefabs for storing game objects rather than scene files. This is a good practice anyway
Get a good diff tool
The other downside of Git is that large file can bloat your repository size. For this reason we tend to have our artists and audio director work in Dropbox while working on their files and we only bring completed versions into the repository and Unity project.
We use branching for different features/versions of the game, especially supporting multiple platforms. We tend to keep all of our platforms in the main development branch and as we approach a release we create a branch for each platform to create platform specific code and speed up making small platform specific fixes. A great article on branching in git can be found here. After release we merge the branches together and continue working in the single main development branch.
I highly recommend checking out Unity Cloud Build for doing continuous integration with Unity. If supports Git and every time you push code to the server the Unity Cloud Build servers will automatically pull this code and make a new build. It currently supports Android, iOS and the WebPlayer.
While Git and source control in general can be daunting to non-technical people on the team it is definitely worth getting everyone up to speed. GUI based clients like SourceTree allow an easier transition to source control, however it’s still good for everyone to have a solid understanding of the underlying principles of Git (or any source control you are using).
If you’re on windows using Powershell then I recommend installing PoshGit. You can get some instructions here.
Conclusion
Please let me know what you think of this tutorial and if I’ve made any mistakes or missed anything out. I tried to keep the tutorial as pragmatic as possible, covering the most common usage of Git. See the links throughout the article for some deep dives into different aspects of Git. What source control are you using? What are your best practices for Git (or any source control) and Unity?
Read more about:
Featured BlogsYou May Also Like
