Version Control and You: Setting up Git for Unity
Version Control, in the simplest possible terms, is the act of creating a back up of your work. The most basic act of this simply taking your project folder and manually copying it in another location. However there is a better way and that way is Git. What is Git? We’ll git to that now.
Git is a command line tool that allows you to store changes in your project to a repository with a few simple commands taking advantage of advanced features such as branching, merging, and working collaboratively with others as well as highlighting your coding skills to the world if you want. This is one of many types of version control systems but is definitely the most popular as of the time of this writing. The two primary online repositories (or repos for short) are Github and BitBucket which both have free options. For this tutorial we’ll be using Github but much of this works just fine for Bitbucket with a few minor tweaks. You can follow their documentation for more details.
First Things First: Setup Your Github Account
First things first, setup an account on GitHub, you can do that by going to GitHub.com and hitting Sign Up in the top right, once you’ve entered your credentials, confirmed your account and signed in you’ll be greeted with your dashboard. This process should be similar on Bitbucket.
Hello Github: Creating a Repository
The next step is creating your first repository (or repo for short) on Github you can do this by clicking on the green “New” button on the top left like so. This process should be similar on BitBucket.
Next you will see the Create Repository screen. Here you will enter important information such as project name, project description, and determine if the project is public or private. In addition you can also add a README, a gitignore, and license for the repo. There are handy descriptors for each of these optional add-ons for the repo, I would just select the .gitignore and look for the Unity template. This is a community maintained template of filetypes that git will ignore when uploading. You can also import an existing repo but we can ignore that for now. An important note, “ main “ is default branch for github, you can change this in the settings if you’d like. This will be important later when we begin merging branches.
First Steps: Installing Git on your PC
Now with your repo set up you can install Git on your PC. Start by heading over to https://git-scm.com/downloads and click on your appropriate OS under Downloads. I’ll be selecting Windows but this process should be similar for MacOS and Linux.
After you download the installer go ahead and run it. Leave the default options as it’s fairly turn key in what it needs to install.
There is a GUI option for Git but this tutorial will be covering the command-line version of Git as it provides the most flexibility and is pretty straight forward. When done a command line should pop up. If for whatever reason it doesn’t show up just open Git Bash from your Start Menu and the command line should popup.
Bash Tacks: Using Git Bash
At first Git Bash (or the command line as it can be known as) can be a little daunting but with a little practice and persistence you can see how easy it is to use. During any point you can type the following to get helpful commands for git. It is important that no matter what you type you always start with git before any commands.
You can use the command line to navigate to your project but the easiest method is just to head to your project root folder and use the context menu to open Git Bash there like so.
Once to the project directory is selected in the Git Bash window go ahead and type
git init
and press enter.
If your project has been initialized before like mine has it will say reinitialized like below. This essentially creates a local repo of your project.
Outside Contact: Linking to your online Repository
With your local repo initialized you can now connect it to your online repo which will save your data in the cloud. You can do this by returning to your Github Dashboard and clicking on your newly minted repo. On the right hand side of the page click the big green “Code” button and either hit the clipboard button or copy the link shown there.
Type the following
git remote add origin [your link here]
this tells git to add the remote repo that exists on Github and link it to your local repo.
The repo was already added in my case hence the “error: remote origin exists” but if successful you with get a fresh line. Now type git remote -v to verify the repo. It should read back the following.
It should return both fetch and push these mean that you can pull from the repo and push to the repo which are important for getting new content (pull) and updating the repo (push) with your changes.
Pull Your Weight: Pulling from the Repo
Before getting started always pull the latest changes from the remote repo with
git pull origin main
this updates your local repo with the most up to date changes from the remote repo. (As mentioned when setting up the repo on Github you can change main to anything you like, in my example this is master) If you already are up to date it will read “Already up to date” like below.
Committed to the Task: Committing changes and updating the Repository
Next you’ll want to check which branch you are on by typing
git branch
this will return the branch you are on and which are available.
You can also see which branch you are on by looking at the command line, it will be in parentheses like so (branch name) but it never hurts to be sure.
Next to want to check if there any changes to the project by typing
git status
this will scan the project for any changes and show them like below.
Adding items to be tracked to be pushed to repository is easy just use
git add [item name]
to add items. The quicker way of doing this is by tracking all changes by using
git add .
as seen below then type
git status
to see what has been tracked or not.
Next you commit the changes that are tracked by typing
git commit -m “[Your Message Here]”
be sure to include the quotes as that serves as the description text. Write meaningful but succinct messages, your later self (or team members) will thank you.
Finally you push the changes to the repo by typing
git push origin main
(or whatever you named your main branch.)It should return the text below which just shows what’s been uploaded and you’re done as you can see here.
You can confirm changes on the Github site as well by going to the repo dashboard and should display your changes.
This is simple diagram is the basic workflow with Git. The only section not covered is git checkout which deals with branches in Git but we will discuss it further below.
Branching Out: Using branches on Git
The power of Git comes from the ability to create multiple lanes or branches of the same codebase. This allows you to main separate copies of the same project for variety of reasons.
For example you could have a feature branch for testing features or fixes and a stable branch that acts as a safe point that you can return to if you have a feature doesn’t work out or if a bug fix totally breaks your project. Once the feature branch is stable enough it can be merged into the stable branch and continue along. This power is multiplied when you work in a team where multiple people are pulling, pushing, merging, and creating branches working on different aspects of the project.
This flowchart illustrates a more complex project with many different branches that sometimes merge into the main or master branch. If you’re a solo developer you may only use one or two branches but if you’re a on a team you may have many multiple branches for different reasons. This is where Git truly shines.
So let’s start branching, if you’re following along you should have one branch which you can see by typing
git branch
I have a few branches on this project.
You can create a new branch by typing
git branch [branch name]
I’ll go ahead and create a bug testing branch. Once you create your branch you can see it in list by typing
git branch
You can switch to your new branch by typing
git switch[branch name]
(you can also use git checkout [branch name] either works) and you should see the command line ending in parentheses change from your current branch to the new branch as well as the prompt confirming that with “Switch to branch [branch name]”.
The work flow for each branch is identical. You still want to Pull, Add, Commit, and Push however unlike before any changes on one branch aren’t reflected on the other. Any changes you do to one branch won’t be seen on the other branch. Only when you merge branches will you see changes on both branches. When you switch branches, those changes will reflect in the Unity project itself so it important to know which branch you are in at all times.
Closing The Loop: Merging Branches
So you have two branches and you’re ready to merge them it is important to remember that when merging branches you have to be in the branch you wish to merge to. If you want to merge the bug testing branch into the master branch. You need to be in master. So start by switching to your chosen branch, in this case master by typing git switch [branch name] and then double checking the branch by typing git branch
With the branch confirmed you can now merge the other branch, in this case bugtesting with the master branch by typing
git merge [name of branch you wish to merge from]
and it should look something like this.
Now finally you’ll want to push the merged branch to your remote repo using
git push origin [just merged branch name]
which will be reflected on GitHub.
Now you have closed the loop merging one branch into another and can begin the cycle again or just continue on the single branch. This is where Git and version controlling moves up to another level. Aside from saving your changes and giving you the ability to restore your project should it implode it allows you to run co-current development without affecting your project allowing you to collaborate on features and troubleshoot issues. Next we’ll talk about reversion and the ability to go back to previous states of your project should something terrible happen.
Turn Back The Clock: Reversion in Git
You did it, you managed to totally screw your project. Panic begins to set in as days, weeks, months, YEARS of work has just been flushed down the toilet and there’s nothing you can do to fix but wait a second you’re using version control like Git. This is the second most important part of having some sort of version control, going back to when you didn’t totally ruin everything with your big ideas. The first step in doing this finding the change logs for that particular branch by typing
git log
which will pull up all the changes to that branch.
You can actually treat these logs as their own branches allowing you to switch to them. For example let’s revert to the change where I just added a cube. You do that by typing
git checkout [commit hash]
like so. It is important you use checkout and not switch otherwise it will throw a error.
You can switch to another branch without any sort of penalty or worry just by typing
git checkout [branch name]
so don’t worry about losing any progress by selecting a previous change. This will all be reflected in Unity.
So there are two options when reverting a project, you can reset the project (undo all changes back to that branch preserving the project) or you can branch off the old change. Let’s try branching the change before nuking the whole project back to an old state.
First go to the change listed in the changelog by typing
git checkout -b [name of new branch] [commit hash]
which should create a new branch from that change in this case I’ll call “Cube Restore Point.” You can confirm the new branch by typing git branch
Now you have a new branch instead of undoing all the hard work retaining your master branch as reference and this new branch with old progress within it effectively saving your project. Now we’ll try doing a full revert to an old version of the project. It is important to remember that by doing this you will remove all the work done past this change so use this cautiously. Doing a manual backup at this point is probably advised.
It’s A Nuclear Device: Reset
The more extreme version of reversion is known as a reset. When you absolutely positively have to eliminate everything, this is your choice. This should be a choice of last resort. A reset will undo every change made up to that point and actually functions much like a reversion just permanently.
Much like in revision you will need the commit hash to reset the repo to and you can either find that via git log or copying the commit has from the Github dashboard to load the commit directly. Make sure you are on the main branch.
To begin a reset you type
git reset --hard [commit hash]
this tells the local repo to reset the HEAD to that process. Unity will reload and reflect those changes.
However, the changes still haven’t been pushed to the repo. So with the changes ready you have to force the changes to the remote repo by typing git push --force origin [main branch] to complete the changes. This wipes out any commits, or branches that are connected past that commit. You can check those changes by going to the Github Dashboard looking at the main branch.
Back Dat Data Up: Backup Of Your Github
The final topic to cover is the manual backup of your Github repository. This is fairly straight forward and probably paranoid endeavor but following the old adage “When you have two of something you really have one, when you have three of something you really have two.” So I’ll show you how to manually make a copy of your Github Repo.
I suggest keeping this on a spare drive or two as you never know and make it a regular ritual, you may never need it but you’ll be glad you did it when you do.
Head to your Github Dashboard and click on the repo of your choice. From there you’ll click on the large “Code” button and select the “Download ZIP” button. It should bring up a prompt and allow you to save it to the place of your choice. That’s it!
With these tools you should be well on your way to committing, merging, revising, and backing up your important project data. I recommend looking at the Git documentation here or the Github documentation here.
Best of luck and now Git out of here!
