Unity + Git, Friends Forever – Pt 1 : Setup

I recently wrote a quick post about how I use Git submodules to manage my code/asset packages in Unity. While writing it I realised how difficult just getting to that stage with version control can be.

We’ve all heard how useful this version control thing is. If you work in a team larger than 2-3, you need it to manage changes to the project. If you don’t, you need it to store backups and history. It lets you reuse code and keep it updated easily. It saves my ass daily (when my laptop died suddenly last week, it took longer to find monitor cables than it did to get my project up and running on another computer). It’ll save your ass daily too.

So, here’s the first a multi-part, step by step guide on how I use Unity with Git on OSX. Yes, there are other methods. Yes, there are other platforms. But I use Git like this.

gitguide intro

This part details how to get your Unity dev system set up with Git for Unity. Part two explains how to do each of the basic tasks with Git. Part three is will be about my “UnityFlow™©” Git workflow (if you already know/use Git, you can skip straight to there). But, for now, setup!

Get Git

Get Git. See Installing and First Time Setup (don’t worry too much if anything is confusing, the defaults will generally work just fine).

If you’re unfamiliar with distributed version control systems, you should (but let’s be honest, you probably won’t) read the Git getting started guide, or the Atlassian Git tutorial.


Sign up for BitBucket

Bitbucket is just an online service that lets you store your Git repositories on their servers. It’s similar to Github, but allows users to host private repositories for free (up to a small number of users). Any hosting provider is fine, you can even set up your own, just make sure you have somewhere to store your projects outside your own computer.

Get SourceTree

SourceTree is a fantastic GUI for Git (and Mercurial), for OSX and Windows 7+(although the Windows version is still in beta and missing some features). Download it here. Yeah, yeah, power Git users only use the command line. Well, the command line makes it hard to see exactly what’s going on, especially if you’re new to Git. It isn’t an either/or thing, use whatever you’re most comfortable with for each task. I’ll be listing instructions for both SourceTree and command line, so don’t fret.

Note: You can add your Bitbucket or Github account details to SourceTree and it will be able to find your hosted repositories.


Setup your Unity project

NOTE: At this point, you’re ready to join an already existing project. If this is the case, and you don’t need to set up a new Git repository, you can skip to Part 2. Just make sure to read the section on cloning at the end of part 2, which will show you how to join a remote and pull the project files onto your computer.

Each Unity project needs its own Git folder (called a repository, or repo). Before you start each project repo, there’s a couple settings you need to change in the Unity editor itself. Open up your project, and go to Edit > Project Settings > Editor. Make sure Version Control Mode is set to Meta Files. This takes all the project data out of obscure files in /Library, and puts each asset’s settings beside it in a file called asset.extension.meta. On Unity Pro you should also change Asset Serialisation to Force Text, this forces as much Unity data as possible, like scene & meta files, to plaintext so that Git (and you) can read, see, and merge changes between commits

Editor settings

Editor settings

Create a Git repo

You’re finally ready to make a new Git repository for your project.


Launch SourceTree, and choose Add Repository(the cylinder with a ‘+’ icon), then in the window that slides down, choose Create Repository. Browse to the root folder of your Unity project, enter a name, and click Create. Your new repo should appear in the bookmarks window, double click to open it in a new window.

Create SourceTree repo
Your project bookmark

Your empty repo

Command line

Navigate to the root of your Unity project, and run git init to set up the repo. You can run git status from this folder at any time to get the current state of the repo. For an empty project like mine, it will look like this.

Git init


Your repo is essentially ready. Git looks at everything in your project folder, and tracks any changes or new/deleted files. However, Unity doesn’t need all of these saved, and including them all can actually cause issues, especially for other users. Since Unity can regenerate a project from the Assets/ and ProjectSettings/ folders alone, we should exclude everything else. To do this, we add a text file with a list of files/folders to ignore, name it .gitignore, and drop it in the main project folder. (Remember that on OSX, files and folders starting with ‘.’ are hidden, and if you use TextEdit, make sure that ‘If no extension provided, use “.txt” ‘ is NOT ticked).

This is my usual .gitignore for unity projects. Make sure to ignore the Library/ and Temp/ folders (Temp/ only appears while Unity is running). The *.extension means to ignore any file with that extension. I also ignore the files generated for Monodevelop/Visual studio, as well as the user preference file.

GitignoreSave .gitignore

If you look at the changed files in SourceTree, or by running git status, you’ll notice that the ignore files/folders have disappeared (they haven’t been deleted though!)

Whew. Actually, that wasn’t too hard, right? You have a Git repo of your Unity project set up, and you’re all ready to start committing and branching to your hearts content! Check out part two for a guide to all the essential Git tasks, and part three for a guide to how to best use Git for Unity development. Any questions, comment or get in touch!

3 thoughts on “Unity + Git, Friends Forever – Pt 1 : Setup”

  1. This is a fantastic series of posts, thanks for sharing your knowledge, it made a huge difference for me.

Comments are closed.