How to use GitHub on a Unity project

If you are completely new to version control and have only heard the word "GitHub" or "Git" in the context of collaborating on a Unity project or backing up files, read on. If you already know about Git and just want to set it up for Unity, scroll down to "How to set up GitHub for Unity".

Why do I need version control, isn’t a Dropbox good enough?

A Dropbox is likely to damage your project. If you have the Unity project open in a Dropbox on multiple computers (which is exactly what happens when you work in a team), Dropbox will sync files instantly. If you are working on the file (say a .unity scene) and your team member is also working on it, this will cause a conflict that Dropbox will resolve by renaming the file. This becomes a nightmare to sort out. Also, WIP scripts that are changed due to file syncing will make it impossible to launch your game.

Version control can sync files as well, but as the name says, with more control. It allows you to:

• To do backups for your project, in case your files get corrupted
• To sync between computers
• To share your files with your team
• It forces you to work in a proper way by committing your work at least once a day
• Adds documentation to your work
• It facilitates team collaboration with features such as file locking, so that you prevent losing work due to the fact that two people have worked on the same file at the same time

Setting up a version control solution takes only a few minutes. It's definitely one of the first things you do when you start a new Unity project. Similar to file synchronization, there are several solutions available.

Different version control systems

As of today, there are 4 solutions worth to mention when it comes to Unity projects.

Unity Collaborate

Unity Collaborate was Unity's own attempt to create a very simple version control solution. Unfortunately, this project has been discontinued and is no longer an option for us.

Git

According to a survey by Stack Overflow, Git is used by 93% of all software development projects. It is free and open source by nature and has a huge ecosystem with services like GitHub, GitLab or Azure DevOps.

Perforce

Perforce is an enterprise-grade version control solution used primarily by AAA game studios. It's known for its great scalability.

Unity Version Control (formerly Plastic SCM)

Unity acquired Plastic SCM in 2021 after Unity Collaborate was discontinued. Unity version control is nicely integrated into the editor.

SVN

SVN (also known as subversion) is a centralized version control solution similar to Perforce.

Can I use it for free?

Each solution has a free option. Perforce can be set up for free for 5 users, but you have to add the cost of running a cloud server if you want to work remotely. Unity Version Control has a free tier for 3 seats and 5GB storage, SVN is also free and open source, but again you have to add the cost of hosting a cloud server.

On Git, there are plenty possibilities, because it has the biggest ecosystem. GitHub has a free tier for unlimited users and gives you 1GB of storage. An alternative is Azure DevOps, which is free for 5 users and unlimited storage. Yes, unlimited, but that might change in the future. There are also free version of Git clients (desktop applications, that push and pull files).

Version control with Git

This article will focus on using Git for version control. We will not go through all the Git commands, because that will be handled by a desktop application.

Git and GitHub

To avoid confusion, Git is the version control system, and GitHub is a cloud service provider that builds upon this system. Git was developed by Linus Torvalds to manage the open-source development of the Linux kernel. The first version was released in 2005, and since then, it has been actively developed and improved by the community with around 1,600 contributors.

GitHub was launched in April 2008 and has around 83 million users (August 2022). Since 2018, it’s owned by Microsoft. GitHub is not the only way to host your Unity project in the cloud. There are plenty of alternatives like GitLab, Bitbucket, or Azure DevOps. It’s also possible to self-host a Git server if you want more control of your data.

Key components of using Git

1. A cloud storage for our central repository (GitHub, Azure Devops or GitLab)
2. A desktop application to push and pull files to GitHub (Anchorpoint, SourceTree, GitHub Desktop)
3. A .gitignore file. This is a configuration, so that we avoid uploading cache files such as “Library”, “Logs” or “Builds”
4. Git LFS. This is an extension that needs to be enabled, so that Git can handle large binary files properly

All of these components will be touched in the next section.

How to set up GitHub for Unity

Setting up GitHub for Unity is actually pretty easy and involves just a few steps.

‍

Configure Unity

You can use an existing Unity project. If you are using Unity 2021 or newer, you don’t need to do any configuration. But just to double-check, make sure that asset serialization is set to force text and that meta files are set to visible. To do that, go to Edit / Project Settings…

‍

File locking

By default, Unity does not respect the read only property of a file. Anchorpoint places a script in the Assets/Anchorpoint folder so that Unity does not overwrite read only files. You can put this script in your Editor Scripts folder. If you can still save to read-only (locked files), just place this C# script in your Assets folder. Preferably under Scripts/Editor.

Setting up GitHub

Setting up GitHub requires just a few clicks.

Setting up your Git desktop application

In this case, we will use Anchorpoint but you can also use any other Git client. If you use another Git client, you have to create the repository on GitHub and then copy the remote URL to your Git client. In Anchorpoint, we will use the GitHub integration.

‍

How does your workflow look like

You want to make daily committing a habit in your workflow. You make a significant change (e.g., you created a new version of your character or implemented a major change to a game mechanic), then you want to commit it. Git commits are fast because they happen locally. When the commit is complete, you can keep working, and all your files are pushed to GitHub in the background.

Branching

Keep it to a minimum. The basics should be a development branch and a release branch. Work on development, and merge to your release branch from time to time. If you want to dig deeper, take a look at the concept of "trunk based development", which explains a proper branching strategy for game development.

What your team members need to do

GitHub

Once your team members are invited by you, they simply need to accept the invite and create a GitHub account. That’s all on GitHub.

Anchorpoint

Your team members will also receive an invite email from Anchorpoint. They have to download and install the application as well as create an account. Once they open Anchorpoint, they first have to accept the invite, and the corresponding project will open automatically.

After clicking on Join Git Repository, Anchorpoint will ask for the place where the files should be downloaded. In some cases, a popup appears that requires to install Git first, before Anchorpoint can proceed with the download.

During the download process, a popup from GitHub will also appear, where your member has to authenticate to GitHub so that Anchorpoint can download the files.

The workflow

When working with Git using Anchorpoint, it is basically a two-button solution. The process is as follows:

1. You do your work in Unity.
2. You open the Timeline in Anchorpoint, add a comment, and press Push.
3. To get your changes, your team member has to Pull them.
4. Your team member does their work in Unity.
5. Your team member comments on their work and presses Push as well.

This workflow is like a file sync with more control. The recommendation is to push changes pretty often so that your team is in sync. It’s about developing a good habit of commenting on pieces of your work so that your whole project process is more transparent.

What happens in case of conflicts?

Sometimes multiple people work on the same asset or scene, which can lead to conflicts that need to be resolved when pulling the files from GitHub.

Conflicts that canbe resolved automatically by Unity’s Smart Merge Tool

When you both work on the same scene but on different objects, your changes can be merged. Git can merge text files, but it is not intelligent enough to merge Unity scenes. For that, you have to use their UnityYAMLMerge tool. To use it, you have to modify the .gitconfig file.

1. Open your Unity project in Windows Explorer.
2. Make hidden files visible.
3. Open a .git folder and open the config file in a text editor.

4. Add the following code:

[merge]
tool = unityyamlmerge

[mergetool "unityyamlmerge"]
trustExitCode = false
cmd = "'path to UnityYAMLMerge'" merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED"

'path to UnityYAMLMerge' should be replaced by the real path to the UnityYAMLMerge.exe on your computer. Usually, you can find it under: “C:/Program Files/Unity/Hub/Editor/2021.3.21f1/Editor/Data/Tools/UnityYAMLMerge.exe”. Make sure that you use forward slashes (/) and not backslashes (\) like Windows is doing.

GitHub limitations

GitHub has some limitations when it comes to storage that can be an issue for game development. If you reach these limitations, a push will be rejected in Anchorpoint and you will get an error message. If these are an issue for your project, you may want to look to other solutions such as Azure DevOps or self-host your Git server using Gitea.

Individual file size limitations

The free version of GitHub limits file sizes up to 2GB. If you are on a paid plan, this limitation increases to 4GB.

Repository limitations

On the free plan, you have 1GB of free storage in your repository. If you need more, you need to buy LFS storage packs.

Frequently asked questions

What is Git in more detail?

Git is a version control solution that was developed for building the Linux kernel and was initially released in 2005. Git is a decentralized version control system. This means that you have a copy of the whole repository on your computer. A repository is basically your Unity project folder on a remote server, e.g., GitHub.

The benefit of working decentralized means that you can fully work offline, you have an automated backup system, and file operations are way faster because you don’t need to wait for a server. To sync with your team, you push (upload) your files to the remote repository, and you pull (download) new file changes from the repository to your local computer. These steps are done manually, in contrast to Dropbox, which is syncing files instantly.

What is Git LFS?

Git was made to deal with code, which is basically a bunch of text files. Games require a lot of binary files like 3D models, textures, sound files, etc. To keep the efficiency and to not download the whole history of your 3D models and textures, Git introduces an add-on in 2014 called Git LFS (Large File Storage). This add-on is now part of almost every Git product and service out there.

It helps to deal with binary files by storing them on a separate location on the remote server and replacing the original file with a 1kb sized pointer. This pointer only knows where the original file is so it can be downloaded to your local computer on demand. This allows you to save storage space.

When you decide on a Git hosting provider (GitHub, GitLab, Bitbucket, or Azure DevOps), you have to look at their Git LFS costs.

Why do I need a .gitignore file?

Unity produces a lot of overhead of files that store caches, build data, or anything else that you don’t want to upload to the Git repository. It will just take away space and slow down your push and pull procedures.

A .gitignore file is basically a filter that tells Git which files, file types, and folders should never be committed to the Git version history. Here is an example gitignore for Unity.

How does branching work?

When a project becomes more complex or the team gets bigger, friction arises. Work in progress commits from e.g. developers can disturb the work of the artist. To prevent this, you can split the project into certain zones. Each zone can then be used by a developer or artist without getting in each other’s way. When the work is finished, these zones are dissolved and merged into the project. Git calls such a thing branches. A short video in our documentation explains them pretty well.

The recommendation is to keep the number of branches very small. The reason is, when you work on your own branch for a long time, you may never run into conflicts. But, once you merge that branch to the main line (imagine this like a giant commit), all conflicts that you ignored have to be solved now. It’s better to run into conflicts early and solve them quickly by working only on one branch.

If you need branches, Anchorpoint allows you to create and switch them in the dropdown in the Timeline next to the Pull button.

Are there good alternatives to GitHub?

GitHub can work great if your project size is pretty small. As soon as you are in the double-digit gigabyte range, it’s smarter to pick another Git hosting provider such as Azure DevOps or self-host your Git server. We made a comparison in 2022 so you don’t need to spend so much time on research.