Using GitHub Desktop as your source control repository in Unity

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.

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. How teammates connect 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

---

Article continues after the advertisement:

Start shopping now

---

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.

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.

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

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.

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

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

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:

---

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

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.

If your .gitignore file is configured to ignore these files, but they are still showing up under your Changes tab, check out this article:

How to fix .gitignore not working on your repository

---

Article continues after the advertisement:

---

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.

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.

3. How teammates connect to the repository

Once the repository is set up, your teammates (i.e. collaborators) will have to connect themselves to your repository to start working with you.

a. Cloning the project files (for collaborators)

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.

How to identify a Unity project folder and open it in the Unity Editor

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.

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.

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.

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.

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:

---