Using Git source control with Unity
Scenes and Prefabs merging
A common problem when working with Unity is when 2 or more developers are modifying a Unity scene or prefab (*.unity files). Git does not know how to merge them correctly out of the box.
Thankfully the Unity team deployed a tool called SmartMerge which makes simple merge automatic.
The first thing to do is to add the following lines to your
%USERPROFILE%\.gitconfig, Linux/Mac OS X:
On Windows the path to UnityYAMLMerge is :
and on MacOSX :
Once this is done, the mergetool will be available when conflicts arise during merge/rebase. Don't forget to run
git mergetool manually to trigger UnityYAMLMerge.
Setting up a Git repository for Unity
When initializing a Git repository for Unity development, there are a couple of things that need to be done.
Unity Ignore Folders
Not everything should be versioned in the repository. You can add the template below to your
.gitignore file in the root of your repository. Or alternatively, you can check the open source Unity .gitignore on GitHub and alternatively generate one using gitignore.io for unity.
To learn more about how to setup a .gitignore file, check out here.
Unity Project Settings
By default Unity projects aren't setup to support versioning correctly.
- (Skip this step in v4.5 and up) Enable
Unity → Preferences → Packages → Repository.
- Switch to
Visible Meta Filesin
Edit → Project Settings → Editor → Version Control Mode.
- Switch to
Edit → Project Settings → Editor → Asset Serialization Mode.
- Save the scene and project from
One of the few major annoyances one has with using Git with Unity projects is that Git doesn't care about directories and will happily leave empty directories around after removing files from them. Unity will make
*.meta files for these directories and can cause a bit of a battle between team members when Git commits keep adding and removing these meta files.
Add this Git post-merge hook to the
/.git/hooks/ folder for repositories with Unity projects in them. After any Git pull/merge, it will look at what files have been removed, check if the directory it existed in is empty, and if so delete it.
Using Git Large File Storage (LFS) with Unity
Git can work with video game development out of the box. However the main caveat is that versioning large (>5 MB) media files can be a problem over the long term as your commit history bloats - Git simply wasn't originally built for versioning binary files.
The great news is that since mid-2015 GitHub has released a plugin for Git called Git LFS that directly deals with this problem. You can now easily and efficiently version large binary files!
Finally, this documentation is focused on the specific requirements and information necessary to ensure your Git life works well with video game development. This guide will not cover how to use Git itself.
Installing Git & Git-LFS
You have a number of options available to you as a developer and the first choice is whether to install the core Git command-line or let one of the popular Git GUI applications deal with it for you.
Option 1: Use a Git GUI Application
This is really a personal preference here as there are quite a few options in terms of Git GUI or whether to use a GUI at all. You have a number of applications to choose from, here are 3 of the more popular ones:
Once you've installed your application of choice, please google and follow instructions on how to ensure it is setup for Git-LFS. We'll be skipping this step in this guide as it is application specific.
Option 2: Install Git & Git-LFS
Configuring Git Large File Storage on your project
If you're using the Git LFS plugin to give better support for binary files, then you'll need to set some file types to be managed by Git LFS. Add the below to your
.gitattributes file in the root of your repository to support common binary files used in Unity projects: