GitHub Desktop
Image from https://desktop.github.com/

Using GitHub Desktop as your source control repository in Unity

Update 11 June 2022: The guide has been updated with an easier way to generate the .gitignore file for Unity projects.

If you’re working on a Unity project with the free Unity license, you’re only allowed to have a maximum of 3 people (and a storage limit of 1GB) on Unity Collaborate Plastic SCM. While you can work around the headcount limitation by adding and removing members when needed, it can be quite a hassle. Hence, for those without a budget for a paid Unity plan, 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 (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 about its intricacies.

Update 4 July 2022: Are you looking for a solution to GitHub Desktop not ignoring the files in your .gitignore? If so, check out this article.

  1. Installing and logging in
  2. Setting up the repository
    1. Creating a GitHub repository
    2. Moving Git files into Unity
    3. Configuring Git ignore
    4. Committing your project
    5. Adding collaborators
  3. Connecting to the repository
    1. Cloning the project files (for collaborators)
    2. Opening the cloned project
    3. Testing the set-up
  4. Fetching and making updates
  5. Wrapping up

1. Installing and logging in

To install GitHub Desktop, you can download the application from their home page.

Once that is done, you 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.

Signing in to GitHub Desktop
Signing in to GitHub Desktop.

2. Setting up the repository

Once you have logged in to your GitHub account, you will need to set up your repository and push some content on to it.

a. Creating a GitHub repository

To be able to commit your Unity project onto GitHub, you’ll first have to create a repository on GitHub. You can do this either on the GitHub website, or from within GitHub Desktop itself.

Since doing it from within GitHub Desktop is the easier way, we will be creating our repository from GitHub Desktop. Go to File > New repository. Then,

  1. Give your repository a name;
  2. 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;
  3. Select Unity under the Git ignore dropdown. This is important, as it ensures that only the essential project files are committed into your repository.
Creating a new GitHub repository for Unity
Make sure that you select Unity under the Git ignore dropdown.

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

GitHub Repository files
Note that the .git folder is hidden by default.

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

b. 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. 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, but read the next section before you make any commits!

Article continues after the advertisement:


c. Configuring Git ignore

Now, before you press the blue Commit to master button, you want to make sure that your .gitignore file is properly configured and in effect. .gitignore controls which files from your Unity project are uploaded onto the Git repository. Unity keeps a lot of user-specific generated files that you don’t want to upload onto the repository, because these files are:

  1. Updated every time you open the project, and;
  2. Cannot be used by other users.

If you have selected Unity under the Git ignore dropdown when creating your repository earlier, GitHub Desktop should only track and commit files from the following folders in your project:

  1. Assets
  2. Packages
  3. ProjectSettings
Check to see if Git ignore is working
If .gitignore is working properly, you should not see files from the Library, Logs and UserSettings folder in the tracked files.

If you see files from either the Library, Logs or UserSettings folder being tracked by GitHub, this means your .gitignore file has not been properly configured. In this case, you will want to open the .gitignore file on a text editor like Notepad, and replace the contents with the following:

.gitignore

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

# MemoryCaptures can get excessive in size.
# They also could contain extremely sensitive data
/[Mm]emoryCaptures/

# Recordings can get excessive in size
/[Rr]ecordings/

# 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
*.aab
*.unitypackage
*.app

# Crashlytics generated file
crashlytics-build.properties

# Packed Addressables
/[Aa]ssets/[Aa]ddressable[Aa]ssets[Dd]ata/*/*.bin*

# Temporary auto-generated Android Assets
/[Aa]ssets/[Ss]treamingAssets/aa.meta
/[Aa]ssets/[Ss]treamingAssets/aa/*

After modifying the file, check GitHub Desktop again. The list of files to be committed will now update. A good way to check if your .gitignore is working properly is to check if there are files in the Library folder being tracked — you should not be committing files from that folder in your project because they are user-specific.

Library files for Unity should not be tracked
If .gitignore is working properly, GitHub Desktop should not be tracking your Library folder files.

d. 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.

e. Adding collaborators

To add collaborators to your project, you will have to:

  1. Log in to GitHub, and add the emails of your collaborators. Once that is done;
  2. Your collaborators will receive an email to accept the invitation to be added as a collaborator;
  3. Now, they will be able to clone the repository from their own GitHub Desktop application and make their own commits to the project.
Invite a collaborator on GitHub
Inviting a collaborator on GitHub

3. Connecting to the repository

Once the repository is set up, your collaborators will have to connect themselves to your repository to start working with you.

a. Cloning the project files (for collaborators)

Update 11 June 2022: If you pull your files from the repository and find files in .gitignore being tracked by the repository, this means you’ve set up your project wrong. Check out this article here on how to fix your .gitignore file being ignored (pun not intended).

To connect to the repository, your other collaborators will have to clone the files from the repository. This will create a copy of the project on their computer that is automatically connected to your GitHub repository.

  1. Go to File > Clone repository on GitHub Desktop.
  2. Select and clone the project that was added onto GitHub (if you don’t see it, then you haven’t been added as a Collaborator).
  3. 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.

b. Opening the cloned project

Once the project has been cloned, to open your project for the first time, you will need to find where you have cloned the project to:

  1. Click on the Show in Explorer / Finder button (or use Ctrl + Shift + F) on GitHub Desktop to identify the newly-cloned project folder.
  2. Take note of the path of the folder that GitHub Desktop opens. This is the folder you will have to Open as a project in Unity.
Finding the cloned Unity project folder.
Finding the cloned Unity project folder.

Once you find the folder, open the project by using the Add button in Unity Hub, or by using File > Open Project in an open Unity Editor.

c. Testing the set-up

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.

4. 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:

  1. Fill in the Summary field. You are recommended to write something descriptive here.
  2. Press the Commit to master button, which will make changes to the project on your computer.
  3. Press the Push origin button, which will apply the updates to your project on GitHub.
First commit in GitHub Desktop
The Push origin button will be where the Publish repository button on the image is.

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.

5. 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.


Article continues after the advertisement:


Leave a Reply

Your email address will not be published.

For security, use of Google's reCAPTCHA service is required which is subject to the Google Privacy Policy and Terms of Use.

I agree to these terms.