How to use GitHub branches with Unity
What is a branch?
Branches are used to develop features, fix bug or experiment in a contained area of your repository.
Let’s say you got a game released and a major bug is found. You don’t know how to fix it so you want to try some things. By creating a branch of the current release version you can safely experiment. It’s always possible to create a branch from an existing branch(ex. release version). After successfully fixing the bug you can merge the branch back to the main version. Which you could then release. This prevents breaking your project.
Branches are even more important when working in a team. By creating branches different people can work on various features of a game. For example a RPG could have branches like inventory, quest, stats etc. If you can work parallel it will speed of the process a lot.
We will go through this process in this article.
Create a branch and switch
To start off show the locally available branches:
git branch
To create a new branch use:
git branch newbranchname
This will be a branch of your current branch.
Next switch to the newly created:
git switch targetbranchname
Using git branch now shows the the newly created “dev” branch and it’s green with an * in front.
While working in this branch I’ll create a script in this Unity project.
With git status we can see the newly created script is detected. If we switch back to “main” git switch main and check with git status you can see it’s detected in the “main” branch as well. You can see the new script in both, because it’s not saved(commit) yet locally in Git.
Let’s head back to the “dev” branch and commit it.
git switch dev
git add .
git commit -m “dev script created”
Now if we go back to the “main” branch git switch main and check git status or in Unity the script is gone. When we go back to the “dev” branch again with git switch dev you can see in Unity the script is back.
This demonstrates how the branches are separated from each other and you can safely experiment in one without affecting the other.
Branch further and merge them back
In this section we will create another few branches. We will create a few as exercise. Imagine we are working on an RPG. Make sure we are basing our branch on “main” for this example. So use git switch main before entering the three commands below.
git branch inventory
git branch quest
git branch stats
Switch to the newly created “inventory” branch: git switch inventory
The “inventory” branch is based on the “main” branch which doesn’t contain the dev script. So if done as instructed in Unity you won’t see the script. This could be the case when you are going to develop on a pre-existing branch. You would want the latest version first before making new changes in the “inventory”. We will need to need to merge with “dev” first.
git merge dev
Now everything from “dev” is included. Next create an inventory script in Unity. This will be our change.
We are going to commit(save) the changes we made to our “Inventory” branch.
git status
git add .
git commit -m “created inventory script”
After that we switch back to “dev” where you there is no Inventory script in Unity. To implement our created inventory into our “dev” branch our “inventory” branch must be committed.
git switch dev
git merge inventory
Everything we did so far is done locally only. Let’s say we want another person to join in to work on the “dev” branch. We follow the next steps:
git status -> To check there’s nothing to commit after the merge.
git push origin dev -> Push “dev” branch to origin(server name). In our case it will be pushed to GitHub so other people can access it too.
(If you get the error “failed unable to access” you need to use git init and push again with git push origin dev . Then you will be asked to login on GitHub)
If successful go to GitHub and you can see “dev” branch is created and can select it.
Pretend we are happy with the “dev” version and want to release it. We will do that by merging dev into main. These are the 3 steps to merge into main:
1. Commit (“dev” branch) we have already done this above. If the changes are not comitted(saved) they won’t be merged into “main” branch.
2. Merge (“dev” into “main”)
git switch main
git merge dev
git status (To check there’s nothing to commit. This is cause it’s already saved with the merge)
If you check GitHub now the changes from “dev” are not applied in “main” branch. Everything is only done locally so far.
3. Push to “main”
git push origin main
Check GitHub main branch and see the changes from the “dev” branch applied.
Closing words
When working alone you can get away with one branch, but in a team you want to be able to work parallel then you’ll create multiple branches. It isn’t too complicated, it’s mostly getting used to. Paying attention to what is saved locally (committed) and what is saved online (pushed) will help a lot.
As mentioned in my previous article remember the three steps especially when working in a team.
1. Pull (pull to get the latest version before adding to your commit)
2. Commit (save it locally)
3. Push (send it to the server)
