Using GitHub Desktop as your source control repository in Unity

If you’re working on a Unity project on the default, free Unity license, you’re only allowed to have a maximum of 3 people (and a storage limit of 1GB) on Unity Collaborate. While you can work around the headcount limitation by adding and removing members as and when they need to make a commit, it can quickly become a tremendous hassle. Hence, for those not willing to pay for a Unity license, a cheap and easy way to go around both the personnel and storage limit is to use GitHub Desktop for collaboration.

GitHub Desktop is a user-friendly way for people to use Git (it is normally accessed through a command line interface). For folks without much experience with source control, GitHub Desktop is a godsend — it allows you to reap the benefits of Git source control without the need to learn its intricacies.

To start using GitHub Desktop, you first need to sign up for a GitHub account so that you can log in to GitHub Desktop. If you are not prompted to log in after opening GitHub Desktop, go to File > Options and you should get this pop-up that you can use to sign in.

Creating a GitHub repository

To be able to commit your Unity project onto GitHub, you first have to create a repository on GitHub by going to File > New repository. Then,

Give your repository a name;
Select a place on your computer to save it to (it’s just a temporary location, so I recommend putting it on your Desktop), and;
Select any option except None under the Git ignore dropdown.

When your repository is created, you should get a folder with the following contents:

GitHub Repository files — Essential files in your GitHub Repository

If you do not see the .git folder, you will need to reveal hidden files on your computer.

Moving Git files into Unity

To turn your Unity project into a Git repository, you will need to transfer the 3 files above into your Unity project folder.

Unity Show in Explorer — Can’t find your project folder? Open your Unity project, right-click over the Project window and select **Show in Explorer** (or **Show in Finder** for Macs).

Note that your Unity project folder is not where the Assets folder is. It is the folder above that.

Moving Git files into Unity project — Move (not copy) the highlighted files from your Git repository into your Unity project.

With the Git files removed, GitHub Desktop will say that it can no longer find your newly-created repository. So click on Locate, and select your Unity project folder (where you moved your Git files to).

Can't find Git repository — Can’t find Git repository

If you’ve done everything right so far, you should see a list of all your Unity project files on the left side of GitHub Desktop, as shown below:

Git repository in Unity project — Your Git repository in Unity is almost done

Article continues after the advertisement:

Configuring Git ignore

Now, before you press the blue Commit to master button, you want to edit your .gitignore file. This file controls what is uploaded into the Git repository, and what is not. Unity keeps a lot of user-specific generated files that you don’t want to upload onto the repository, because they are updated every time you open the project, and they cannot be used by other users. So, you want to use .gitignore to exclude these files.

Open the .gitignore file using a text editor, and replace its contents with the following:

#Ignore all files and folders.
/*

#Except the Assets and ProjectSettings folder, as well as the selected Git files.
!Assets/
!ProjectSettings/
!.gitignore
!.gitattributes

These settings will cause GitHub Desktop to commit only the Assets and ProjectSettings folders, as well as the .gitignore and .gitattribute files onto the repository.

Note: If your project happens to use additional Packages (i.e. added with Unity’s Package Manager), then you will need to add the Packages folder into your .gitignore too.

Committing your project

To commit your project onto your repository, you will need to fill in the Summary field, then press the Commit to master button. After that, press the Publish to repository button on the top right.

First commit in GitHub Desktop — Although it’s not compulsory, it’s a good idea to also fill in the **Description** field if you have more details about the commit to include.

You (and your collaborators) will have to go through this same process every time you make changes to the project. After the first commit, however, the Publish repository button will become Push origin. Both buttons do the same thing.

To add collaborators to your project, you will have to log in to GitHub, and add the emails of your collaborators so that they can pull the repository down from their GitHub Desktop interface and make their own commits to the project.

Pulling down the project files

This section has been updated on 3 June 2020, as we found a simpler way to open the cloned repository from Unity.

Once the files are uploaded, other collaborators will be able to pull the files down from the repository. The first time will require some basic set-up:

Go to File > Clone repository on GitHub Desktop.
Select and clone your project repository onto the Desktop (if you don’t see it, then you haven’t been added as a Collaborator).
Open one of the Unity scene files from the project. Unity should automatically compile some files and open the scene (as well as the project) for you. Alternatively, you can open the GitHub folder as a project in Unity.

To test if your set-up is working, make some small changes to your Unity project and see if the changes are reflected inside GitHub Desktop. Once done, you can right-click over the left bar where the changes are listed, and select Discard all changes to undo them.

Discarding your changes on GitHub Desktop — You can also select to under changes only on specific files or folders by using the checkbox on the left of the file name.

Fetching and making updates

After publishing or cloning your repository, before you do any work on your project, remember to go to GitHub Desktop first, and click on the Fetch origin button in your repository. This updates your repository with any changes your collaborators may have made.

Fetch origin on GitHub — This updates the local copy of your project.

Then, as mentioned above, if you make changes to your project, GitHub Desktop tracks and lists them on the left column of its interface. To commit these changes, you will need to do 3 things:

Fill in the Summary field. You are recommended to write something descriptive here.
Press the Commit to master button, which will make changes to the project on your computer.
Press the Push origin button, which will apply the updates to your project on GitHub.

As a rule of thumb, before any commit, it is good practice to look through at all the changed files. This will prevent you from committing any unintended changes.

Wrapping up

Although source control is a relatively simple concept, it takes a fair bit of trial and error to grasp. If this is your first time setting up a repository, I recommend doing frequent backups of the project (just ZIP up your Unity project folder and store it somewhere). It’s not uncommon for files to be lost due to careless commits, or for changes to be overwritten because another collaborator forgot to do a fetch before starting work.