Git is a version control system, which allows you to track all changes you make to your project, and easily share those changes with your teammates. We highly encourage you use git for your projects, since it’s much more sophisticated than things like google drive or copying files on flash drives. Here, we’ll go over the basics of git, and how to get it set up properly with Unity.

Setup

Install a git client

The first thing you need to do is install a git client. For beginners and non-CS majors, we recommend GitHub desktop. This will give you a nice-looking and intuitive UI that should help you focus on project development and collaboration rather than trying to get git working.

However, if you’re a CS major, then at some point you may want to learn how to use the git command line. This can have a rather steep learning curve compared to GitHub desktop. However, once you learn how to use it, you may find that it’s more efficient and powerful than the GUI client. If you’re interested, you should look research this for yourself.

1. Download GitHub desktop from here, and run the installer.
2. When prompted, enter your existing GitHub account, or create a new one. You’ll need this to sync your changes with your teammates.
3. Once installed, GitHub desktop will open with 3 options. For now, just leave it open and don’t do anything.

Repositories

A repository is a folder containing your entire project, as well as its entire history, and some other information on how to exchange changes with your teammates. Here, we’ll create your project and set up a github repository.

Creating a Project and Repository

NOTE: Only one person on your team should do this.

Unity Setup

1. Open Unity, and click “NEW”
2. Enter your project information. Your project name must not contain spaces, otherwise GitHub won’t like it.
3. Click “Create Project”

Git setup

1. Click “Create New Repository” (the first option on the left)
2. Under “Local path” choose the same path that you used while setting up your Unity project. This is not the path to your unity project itself, but to the directory containing your unity project.
3. Under “Name” enter the name of your project. This must be exactly the same as your Unity project name.
4. Make sure “Git ignore” is set to “Unity”, which will make git ignore any unnecessary temporary files that Unity generates.
5. Click “Create Repository”

GitHub Setup

1. Click “Publish repository” on the top
2. If you want, check the box that says “Keep this code private”. In order to do this, you will need to upgrade your GitHub account. You can do this for free here as long as you’re a student. This might take a while to actually affect your account, but you can always make your repository private later.
3. Log onto github.com, and select your repository on the right. Then navigate to the “Settings” tab.
   
   
4. Under “Options”, make sure “Restrict editing to collaborators only” is checked
5. Under “Collaborators”, add the github accounts of all of your teammates.

Cloning a Repository

NOTE: Everyone else on the team (i.e. the person who didn’t create the project repository) should do this.

1. On the GitHub desktop startup page, select “Clone a repository”
2. Click the “URL” tab, and paste the GitHub URL to the project
3. Set “Local path” to wherever you want your project to be
4. Click the “Clone” button

Staging and Commiting

At this point, everyone should now have a copy of the project. Now it’s time to make some changes! Head on into Unity, and do a bit of work on your project. Once you’re done, open up GitHub Desktop again. At this point, you’ll need to know some terminology:

• A commit is a snapshot of your entire project at a certain point in time. These snapshots are stored only when you want them to, and have a description of their changes from the previous commit attached to them.
• Staging is the act of selecting which files are going to end up in your next commit. If you only select some files to commit, then you can send just those files to your teammates while keeping other changes to yourself.

Under the “Changes” tab, you’ll notice a list of files that were either added or changed. If you click each file, you can see what changed. Files with a check box next to them are considered staged, meaning they will be added to the next commit.

When you’re ready to commit your changes, simply enter a short summary and description in the bottom left corner, and click the “Commit” button! You can also switch to the “History” tab, which will show you the complete history of your project.

Pushing and Pulling

When you commit a change, that change doesn’t automatically go out to everyone on your team. At first, it’s only on your own computer.

1. Click “Push Origin” to send your changes to GitHub (top right)
2. You and your teammates should periodically click “Fetch origin” or “Pull origin” to get the latest changes on GitHub

Branches

Unlike google docs, git does not sync your changes with your teammates in real time. This means that your team could start out with everyone working on the same copy of the project, but then everyone could make their own different changes to that copy at the same time. This would turn into a giant mess once everyone tried to exchange their commits with each other. To handle this, we recommend you use branches.

A branch is basically just a long chain of commits. At the top of the chain is the head commit, which is your most recently committed version of your project. The branch also includes every single commit that came before the head commit. Commits could be part of more than one branch at the same time as well.

By default, there is always a branch called “master“. However, we recommend that each team member create their own branch, and make all their changes in that branch. To create a branch:

1. In the top menu, go to “Branch > New Branch”
   
2. Create a unique branch name (probably your own name). Make sure “master” is selected under “create branch based on”
3. Click “Publish Branch”

Now, as long as you have your own branch selected under “Current branch”, your changes will not affect your teammates’ changes. We’ll call these development branches. The difference between this and the master branch is that the development branches should have just your own latest changes, while the master branch should have only changes that are ready to be shared with everyone else.

Switching between branches will replace your current version of the project with the project from the branch you selected. This is called a checkout.

When you commit to your own branch, it advances by one commit without affecting any other branches. For example, if Marek decides to make a change, the master and marek branches may look something like this:

If Joe Bruin also commits to his own branch, all three branches may look like this:

At the moment, everyone is pretty much working on their own version of project independently. This is where merging comes in.

Merging

Suppose Marek and Joe Bruin want to combine their changes together. This is known as merging. For the most part, we don’t recommend merging directly between development branches unless you know what you’re doing. Instead, you should normally go through the master branch. You need to do these two things in order:

Merge master into your development branch (Update from default branch):

1. Make sure your own branch is selected
2. Fetch origin
3. In the top menu, go to “Branch > Update from default branch”.
4. Push origin

This will merge your branch with any changes that have since been added to the master branch. If there were no changes, then this will do nothing. If the merge is successful, it will add a new merge commit. However, things can go wrong: see “Merge Conflicts” below.

Fast-forward master into your development branch:

1. Switch “current branch” to master
2. In the top menu, go to “Branch > Merge into current branch”
3. Select your own branch and click the merge button
4. Click “Push origin” (ONLY if you’re sure there were no merge conflicts, more on this later)
5. Don’t forget to switch back to your own branch!

It is very important that two people don’t try to update master at the same time. You should coordinate with your teammates before doing this, or just designate one person to deal with the master branch. If you do everything right, this step should not create a new merge commit.

Finally, you may want to tell your teammates to merge master into their own development branches, so that they can get your changes as soon as possible.

If you know what you’re doing, you can merge between development branches if you want. This could be useful if someone else has a change that you want, but they aren’t ready to merge it into master yet. However, for the most part you should only be merging with master.

Merging Example

From the example above, let’s say Marek tries to update master first. He first tries to merge master into his branch, which does nothing because master had not been updated since he started working on top of it. At this point, our commit tree looks like this (same as before):

Marek now fast-forwards master into his own branch. Fast-forwarding is really just a special type of merge where all you do is move the master branch up to a later commit. The commit tree now looks like this:

Now, Joe Bruin wants to update the master branch with his changes. He first merges master with his development branch. This creates a new merge commit. Our commit tree now looks like this:

After fast-forwarding master:

And finally, after Marek (hopefully) updates from master:

And now everyone is on the same page!

Merge Conflicts

In the above example, the changes by Marek and Joe Bruin were independent of each other. But what if they weren’t? Suppose Marek and Joe Bruin made the following changes independently:

Marek’s changes:

Joe Bruin’s changes:

Marek updates the master branch first, and all goes well. However, when Joe Bruin tries to merge master into his branch, he’ll run into trouble:

For text files (mostly code), git will insert markers where the conflict happened:

To fix this:

1. Manually edit the file to fix the conflicts
2. Commit
3. Push origin

We recommend everyone coordinate in advance to avoid merge conflicts in the first place.

A merge conflict will also occur for all non-text files (assets like sprites, sound effects, etc), and may happen frequently for some Unity-generated text files (scenes), which you really shouldn’t edit by hand. Fixing these merge conflicts is tough to do with GitHub desktop, so just ask for help if this happens to you. To avoid this, we recommend you coordinate with your teammates and make sure two people don’t try to change the same assets or Unity scenes.

Reverting

Sometimes, you’ll make changes that you want to undo. Thankfully, this is very easy with git.

Reverting to the Last Commit

Under the changes tab, simply right-click on the file(s) that you want to revert, and select “Discard changes”.

Reverting Committed Changes

Under the “History” tab, right click the commit you want to revert, and click “Revert this commit”. This will add a new commit that will reverse the effects of your chosen commit.