How to use Git for Unity3D source control?

What are best practices for using Git source control with Unity 3D, particularly in dealing with the binary nature of Unity 3D projects? Please describe the workflow, what paths would be included in .gitignore, what settings should be set in Unity and/or the project, and any other special things that should be noted.

Note: I realize that using the Asset Server is the Unity-recommended way, but I would like to use Git for a variety of reasons. Please no answers that state or argue that I should just use the Asset Server. The Asset Server really isn't an option for me.

The following is an excerpt from my personal blog .

Using Git with 3D Games

Update Oct 2015: GitHub has since released a plugin for Git called Git LFS that directly deals with the below problem. You can now easily and efficiently version large binary files!

Git can work fine with 3D games out of the box. However the main caveat here is that versioning large (>5 MB) media files can be a problem over the long term as your commit history bloats. We have solved this potential issue in our projects by only versioning the binary asset when it is considered final. Our 3D artists use Dropbox to work on WIP assets, both for the reason above and because it's much faster and simpler (not many artists will actively want to use Git!).

Git Workflow

Your Git workflow is very much something you need to decide for yourself given your own experiences as a team and how you work together. However. I would strongly recommend the appropriately named Git Flow methodology as described by the original author here.

I won't go into too much depth here on how the methodology works as the author describes it perfectly and in quite few words too so it's easy to get through. I have been using with my team for awhile now, and it's the best workflow we've tried so far.

Git GUI Client 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. But I would like to suggest the free SourceTree application as it plugs in perfectly with the Git Flow extension. Read the SourceTree tutorial here on implementing the Git Flow methodology in their application.

Unity3D Ignore Folders

For an up to date version checkout Github maintained Unity.gitignore file without OS specifics.

# =============== #
# 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

Unity3D Settings

For versions of Unity 3D v4.3 and up:

1. (Skip this step in v4.5 and up) Enable External option in Unity → Preferences → Packages → Repository.
2. Open the Edit menu and pick Project Settings → Editor:
   1. Switch Version Control Mode to Visible Meta Files.
   2. Switch Asset Serialization Mode to Force Text.
3. Save the scene and project from File menu.

---

Want you migrate your existing repo to LFS?

Check out my blog post for steps on how to do it here.

Additional Configuration

One of the few major annoyances one has with using Git with Unity3D projects is that Git doesn't care about directories and will happily leave empty directories around after removing files from them. Unity3D 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 Unity3D 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.

In Unity 4.3 you also had to enable External option from preferences, but since Unity 4.5 they dropped option for that, so full setup process looks like:

1. Switch to Visible Meta Files in Editor → Project Settings → Editor → Version Control Mode
2. Switch to Force Text in Editor → Project Settings → Editor → Asset Serialization Mode
3. Save scene and project from File menu

Also our team is using a bit more extended .gitignore file:

# =============== #
# 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

Note that the only folders you need to keep under source control are Assets and ProjectSettings.

More information about keeping Unity Project under source control you can find in this post.

What is GIT?

Git is a free and open source distributed version control system (SCM) developed by Linus Torvalds in 2005 ( Linux OS founder). It is created to control everything rom small to large projects with speed and efficiency. Leading companies like Google, Facebook, Microsoft uses GIT everyday.

If you want to learn more about GIT check this Quick tutorial,

First of all make sure you have your Git environment set up.You need to set up both your local environment and a Git repository (I prefer Github.com).

GIT client application Mac/Windows

For GIT gui client application i recommended you to go with Github.com,

GitHub is the place to share code with friends, co-workers, classmates, and complete strangers. Over five million people use GitHub to build amazing things together.

Unity3d settings

You need to do these settings

Switch to Visible Meta Files in Edit → Project Settings → Editor → Version Control Mode.

Enable External option in Unity → Preferences → Packages → Repository

Switch to Force Text in Edit → Project Settings → Editor → Asset Serialization Mode.

Source: Using Git With 3D Games Source Control

To add to everything stated, it is also ideal to use git lfs with Unity. I have been using this since it came out and I had no trouble with it.

You will want to add this .gitattributes next to your .gitignore file

*.cs diff=csharp text
*.cginc text
*.shader text

*.mat merge=unityyamlmerge eol=lf
*.anim merge=unityyamlmerge eol=lf
*.unity merge=unityyamlmerge eol=lf
*.prefab merge=unityyamlmerge eol=lf
*.physicsMaterial2D merge=unityyamlmerge eol=lf
*.physicsMaterial merge=unityyamlmerge eol=lf
*.asset merge=unityyamlmerge eol=lf
*.meta merge=unityyamlmerge eol=lf
*.controller merge=unityyamlmerge eol=lf

*.a filter=lfs diff=lfs merge=lfs -text
*.mp3 filter=lfs diff=lfs merge=lfs -text
*.wav filter=lfs diff=lfs merge=lfs -text
*.aif filter=lfs diff=lfs merge=lfs -text
*.ttf filter=lfs diff=lfs merge=lfs -text
*.png filter=lfs diff=lfs merge=lfs -text
*.jpg filter=lfs diff=lfs merge=lfs -text
*.exr filter=lfs diff=lfs merge=lfs -text
*.fbx filter=lfs diff=lfs merge=lfs -text
*.FBX filter=lfs diff=lfs merge=lfs -text
*.rns filter=lfs diff=lfs merge=lfs -text
*.reason filter=lfs diff=lfs merge=lfs -text
*.lxo filter=lfs diff=lfs merge=lfs -text

That is my rolling file list. If you use additional binary files not listed, add them.

I also have files configured to use yamlmerge, you would need to set this up. You can read about it here: http://docs.unity3d.com/Manual/SmartMerge.html

I thought that I might post a simpler .gitignore for anyone that is interested:

# Ignore Everything
/*

# Except for these
!/.gitignore
!/Assets
!/Packages
!/ProjectSettings

We now have seamless integration to unity with Github to Unity extension... https://unity.github.com/

The new GitHub for Unity extension brings the GitHub workflow and more to Unity, providing support for large files with Git LFS and file locking.

At the time of writing the project is in alpha, but is still usable for personal projects.

The main things to remember when using git for unity-3d source code version control:

(A) DO NOT check-in the Library folder. I have made this mistake multiple times in past and have suffered for it! Delete OR move out library folder before adding your project / files into git.

(B) Use "Visible Meta Files" - for newest unity versions - 5.3.4 and above this happens by default. For some of the earlier versions you need to change the settings under: Edit-> Project Settings-> Version Control

(C) Use a .gitignore file for Unity- to make sure sanity is maintained and files are not unnecessarily added- if on android / tizen - add rules to exclude APK and TPK files from being added to repository. Google around for a .gitignore file for unity OR else use this model .gitignore for Unity provided by GitHub: https://github.com/github/gitignore/blob/master/Unity.gitignore

(D) Make sure the .gitignore file is added to the repository as the first file added - because in past I personally have missed adding .gitignore file. Have many thoughts in hindsight on why this happened- but nowadays I just copy and add .gitignore file as first step of setting up repository.

So... to make a Unity project ready for git, do the following:

(1) Go to project folder

(2) Type git init .

(3) Copy the .gitignore file: On MacOS: cp ~/Downloads/.gitignore On Windows: copy c:\Users[yourusername]\Downloads.gitignore .

(4) git add .gitignore

(5) git add *

Hope this helps... all the best!

I would rather prefer that you use BitBucket, as it is not public and there is an official tutorial by Unity on Bitbucket.

https://unity3d.com/learn/tutorials/topics/cloud-build/creating-your-first-source-control-repository

hope this helps.

Edit -> Project Settings -> Editor

Set Version Control to meta files. Set Asset Serialization to force text.

I think this is what you want.

Only the Assets and ProjectSettings folders need to be under git version control.

You can make a gitignore like this.

[Ll]ibrary/
[Tt]emp/
[Oo]bj/

# Autogenerated VS/MD solution and project files
*.csproj
*.unityproj
*.sln
*.suo
*.userprefs

# Mac
.DS_Store
*.swp
*.swo

Thumbs.db
Thumbs.db.meta

.vs/

You can use Github for Unity, a Unity Extension that brings the git workflow into the UI of Unity.

Github for Unity just released version 1.0 of the extension.

• It uses git-lfs (git large file support) to properly store big assets
• File Locking so that nobody else overwrites your asset commits
• Push and Pull to/from any remote repository
• You can also download it in the Unity Asset Store: https://assetstore.unity.com/packages/tools/version-control/github-for-unity-118069

Unity also Provide its own Source version control. before unity5 it was unityAsset Server but now its depreciated. and launch a new SVN control system called unity collaborate.but the main problem using unity and any SVN is committing and merging scene . but Non of svn give us way to solve this kind of conflicts or merge scene . so depend upon you which SVN you are familiar with . I am using SmartSVN tool on Mac . and turtle on windows .

Just adding in on the subjet of Gitignore. The recommended way only ignores Library and Temp, if its wihtin root of your git project. if you are like me and sometimes need unity project to be a part of the repo, not the whole of the repo, the correct strings in gitignore would be:

**/[Tt]emp
**/[Ll]ibrary
**/[Bb]uild

I wanted to add a very simple workflow from someone who has been frustrated with git in the past. There are several ways to use git, probably the most common for unity are GitHub Desktop, Git Bash and GitHub Unity

https://assetstore.unity.com/packages/tools/version-control/github-for-unity-118069.

Essentially they all do the same thing but its user choice. You can have git for large file setup which allows 1GB free large file storage with additional storage available in data packs for $4/mo for 50GB, and this will allow you to push files >100mb to remote repositories (it stores the actual files on a server and in your repo a pointer)

https://git-lfs.github.com/

If you don't want to setup lfs for whatever reason you can scan your projects for files > 128 mb in windows by typing size:large in the directory where you have your project. This can be handy to search for large files, although there may be some files between 100mb and 128mb that get missed.

The general format of git bash is

git add . (adds files to be commited)

git commit -m 'message' (commits the files with a message, they are still on your pc and not in the remote repo, basically they have been 'versioned' as a new commit)

git push (push files to the repository)

The disadvantage of git bash for unity projects is that if there is a file > 100mb, you won't get an error until you push. You then have to undo your commit by resetting your head to the previous commit. Kind of a hassle, especially if you are new with git bash.

The advantage of GitHub Desktop, is BEFORE you commit files with 100mb it will give you a popup error message. You can then shrink those files or add them to a .gitignore file.

To use a .gitignore file, create a file called .gitignore in your local repository root directory. Simply add the files one line at a time you would like to omit. SharedAssets and other non-Asset folder files can usually be omitted and will automatically repopulate in the editor (packages can be re-imported etc). You can also use wildcards to exclude file types.

If other people are using your GitHub repo and you want to clone or pull you have those options available to you as well on GitHub desktop or Git bash.

I did not mention much about Unity GitHub package where you can use GitHub in the editor because personally I did not find the interface very useful, and I don't think overall its going to help anyone get familiar with git, but this is just my preference.

I suggest that you make a .gitignore file that includes everything other than the assets folder (all the other files that are originally inside a unity project). Next, you should place all your game projects in one folder. Next, duplicate the .gitignore in every single project folder for your games. This will exclude the libraries and unnecessary folders inside your projects other than the assets. If you have any projects you don't want, then put them in a new .gitignore inside where your game projects are stored. Note: You can have multiple .gitignore's and .gitignore is based on relative paths. I hope that helped!

I have tried this approach with my friend in a 72 hour game jam, please note that they were not aware of GIT.

First I create empty repo in [GitHub][1] (private repos is now free) with the the predefiened .gitignore unity tempelate, it should be the same as this:

# This .gitignore file should be placed at the root of your Unity project directory
#
# Get latest from https://github.com/github/gitignore/blob/master/Unity.gitignore
#
[Ll]ibrary/
[Tt]emp/
[Oo]bj/
[Bb]uild/
[Bb]uilds/
[Ll]ogs/
[Mm]emoryCaptures/

# Asset meta data should only be ignored when the corresponding asset is also ignored
!/[Aa]ssets/**/*.meta

# Uncomment this line if you wish to ignore the asset store tools plugin
# /[Aa]ssets/AssetStoreTools*

# Autogenerated Jetbrains Rider plugin
[Aa]ssets/Plugins/Editor/JetBrains*

# Visual Studio cache directory
.vs/

# Gradle cache directory
.gradle/

# Autogenerated VS/MD/Consulo solution and project files
ExportedObj/
.consulo/
*.csproj
*.unityproj
*.sln
*.suo
*.tmp
*.user
*.userprefs
*.pidb
*.booproj
*.svd
*.pdb
*.mdb
*.opendb
*.VC.db

# Unity3D generated meta files
*.pidb.meta
*.pdb.meta
*.mdb.meta

# Unity3D generated file on crash reports
sysinfo.txt

# Builds
*.apk
*.unitypackage

# Crashlytics generated file
crashlytics-build.properties

Then I've created a main scene, this scene shouldn't be modified by any individual while they are development, It should be the demo scene for all dev and artists in the team to test the latest features in game. First of all any new feature should be in a separate branch from main, also each team member has his own scene that he use it for testing and development. once everything is good he/she made a PR reviewed by other members. If the merged feature is complete then we add it to the main scene so that all other members see the impact and the progress.

Regarding the art files, It's better to avoid conflicts by having variations of sprite files and replace the main sprites with the fully new adjusted ones from PRs. [1]: https://github.com/

if you use source control, make sure you have a git ignore for the useless files: https://github.com/github/gitignore/blob/main/Unity.gitignore

I would strongly suggest you switch over to PlasticSCM. It's something Unity has migrated to and provides a designer cum developer workflow to manage version control for something complex like game development.

You can get the cloud edition for 3 users for free. This replaces Unity's Collaborate tool.

Note: I really struggled using Git/Bitbucket and SourceTree for managing a simple project.

https://unity.com/products/plastic-scm