Setting up Version Control with Git for Unity
In this article, I will be walking you through how to set up version control with Git for Unity Projects. This is a tutorial that will be good for those unfamiliar with setting up version control for any kind of software development project but will be especially useful to those setting up version control for Unity.
**To be clear, this article will not go over the Command Line Interface (CLI) nor any of its commands, nor how to install it into your system. For a better understanding of the CLI, check out the following link where I believe w3schools.com documents it well. I also will not be covering all Git commands. I will only cover what is needed to set up your project.
The Breakdown
To get your project set up with Git version control, there are a few steps you will have to follow. I will break down these steps here and then go into more detail about them in the rest of the article. The steps are as follows:
- Downloading and Installing Git (if you do not already have Git installed)
- Selecting your Repository Host Provider
- Creating a Github Repository
- Linking Github to your Local Project
- Committing and Pushing changes (Bonus)
More or less only four steps, so follow me along in this article and you should have a project set up with version control in an hour or less.
Downloading and Installing Git (if needed)
Before you can start using Git, you need to make it available for use on your computer. Now, some computers already have Git installed and available for use from the moment you open it up (this is especially true for Apple Mac products). To check if your computer already has git installed, open up your CLI and type in “git version”. If installed, you should get a message similar to the image below.
If you do not have Git readily available on your machine, then there are a few ways you can install it. If running MacOS, one of the easiest ways would be to simply download and install Xcode. For Linux, Windows, and other MacOS installation options, check out Git’s documentation for installing Git here, where links to downloads for each operating system can be found. Once set up, next we can tackle Selecting your Repository Host Provider.
Selecting your Repository Host Provider
Now when it comes to source code repository host providers, there are tons of options. I mean there is PlasticSCM, Perforce, Apache Subversion, Mercurial, and more. All version control systems and host providers have their pros and cons, and I definitely recommend looking into them to see what they are. Since this is a tutorial to set up version control with Git, and since these are the two host providers I have used for all of my software development projects, I recommend using GitHub or BitBucket. In this tutorial, I will go over setting your project up in GitHub but feel free to use BitBucket if you so please as most-to-all steps will be the same. Set up your account with your selected provider, if you don’t already have one, and then let’s start the next step of actually Creating a GitHub Repository.
Creating a GitHub Repository
If you followed me along in choosing GitHub as your provider, you should find yourself on a screen similar to the image below.
On the left-hand side in my image, underneath where it says repositories, you can see some of the projects I currently have set up and connected to my git repo (some are public, and some are private). To create a new project, hit the green button that says “New” above the repositories section I just mentioned. This should take you to a page similar to the following image.
Name your repository an appropriate name for your project. For this tutorial, I will simply name my repository “TutorialRepo”. Add a description if you would like. Once done, your next options are to make the repository Public or Private. Which option you select depends on your project and whether or not it has been deemed something the public has access to view or something you want to keep private for only a select few to see. Next, you can add a README file, but this can be added at a later date, so there is no need to add it now if you don’t want to. You can also select whether or not to add a .gitignore file and even the license your project has. Since I am creating a repository for a Unity project, I recommend using the Unity .gitignore template. This gets you set up with a .gitignore file that prevents certain, unnecessary Unity files for version control, from being stored in your repository. Your project creation screen should look similar to the image below.
Once you are ready, hit the green “Create Repository” button at the bottom of the page. This will create your project, and once done, you should find yourself on your project’s repository screen which should be similar to the image I am showing below:
If everything is looking right, we can now start on the last part of this tutorial: Linking GitHub to your Local Project.
Linking GitHub to your Local Project
At this point, if you have not created your Unity project you would like to link to version control, then do so now. If you are not sure how to create a new Unity project, check out my tutorial here that covers this.
Now, to link your project that is on your local computer to GitHub, we will be making heavy use of the CLI. Open up your CLI and navigate into the folder containing your project. For this tutorial, I have named my project “TutorialProject”. If done correctly, you should find yourself in your project’s directory. As an example, my CLI after navigating into my project’s directors is as follows:
Once in your project’s directory, on your CLI, type in git init. This first step initializes your project to be tracked by Git. Your CLI should now look similar to the image below once you have run the command.
After initializing your project, you want to head back to your project repository on GitHub and you want to grab the URL to connect your local project to it. This URL can be found by clicking on the green button that says “Code” within your project’s repository screen. There will be a small drop-down that appears. When linking your project, you have three options with GitHub as to how you can do that. These three options are HTTPS, SSH, and GitHub CLI. I often use HTTPS, and that is what I will demonstrate here. Copy the URL provided, and keep that copied as we will be using it in a second. For reference, this is how the drop-down and URL should look when trying to grab this data:
Go back into your CLI now, and type in git remote add origin [your project URL]. Once done, hit enter. If you did not get any response from the CLI, then that is a good sign at the moment. To verify your project was actually able to connect with GitHub, type in git remote -v. You should see that your project is now connected to your GitHub repository! To serve as an example, this is how my CLI looks after running both commands:
Now, technically speaking, your project is now connected to version control, and you have a repository host provider to help track changes and progress in a more visual format. As such, we can bring this tutorial to a close, but if you would like to go over committing and pushing, then keep following along for the next section.
Committing and Pushing Changes
Now, before we even go into making commits and pushes, there is one more command that a software developer must always do first. This command that must be done first is called a pull. When working on software development projects, it is not uncommon for there to be multiple developers working on the same project. This means there are multiple developers also making changes and committing them to the project. As such, to save yourself from what is usually a major headache when dealing with merge conflicts, just do yourself a solid and run the git pull command to download and merge all changes that you do not have in your current local copy of the project. If you run the git pull command, you should get the following message:
As you can see, there was some content downloaded, but Git warns us that no tracking information is set up. This can be solved in multiple ways. For now, simply type in git pull origin [name of your main/master branch]. In my case, I end up with the following after running the above command for my project:
Now with our project setup to properly pull and having pulled all content that was already in the repository (which in my case was just the .gitignore file I created earlier), we can begin with the process of committing changes. When a project is initialized with Git for the first time, all content within that project must be committed and pushed to be tracked. To see how these next few commands will affect your project’s versioning, type in the command git status. The results of my git status can be seen in the previous screenshot of my CLI. You should see pretty much all files and directories as red. This means those files are currently not being tracked for changes. To track them, type in either “git add *” or “git add .” Both commands will add all untracked files to be tracked. Once running the git add command, type in git status, and you should see all the files are now green, meaning they are being tracked.
When looking at the directories and files now being tracked, you may notice that not all of the directories from when we ran git status earlier are not being tracked. This is because those directories and any files within them are being excluded from being tracked by the .gitignore file I generated earlier when creating the project. Now that we have our files being tracked, the next step is to commit them. When committing, you want to write a short message explaining what it is you are committing to the project with this push. As such, type in the command git commit -m “[your message here]”, where for now, you can have the message be “First Commit”. This is my CLI after running the commit command:
Now our last step is to push all of our changes so we can see them on our Github. If you type in the command git push and this is your first time making a push to a branch, you will be greeted with an error message that says fatal: the current branch master has no upstream branch. This error is similar to what we ran into when trying to pull earlier. To fix this, simply use the command git push --set-upstream origin [branch name]. This command only needs to be done once per branch, and it will push all of your tracked files to your GitHub repo, where you can verify to see if it indeed did work. The result of your push should be similar to the image below:
You may notice that in my CLI, my username and password were asked for, and you may have gotten something similar. This feature is currently deprecated and will be gone in the future due to security reasons, but for now, this can be used in the meantime. To get around this, you need to set your git credentials.
**Note: When making GitHub projects, the starting, head branch is named “main”. When making projects in Git through the CLI, the head branch starts as “master”, which is why I had to push to the “master” branch in the above screenshot. To change your head branch to “main”, I recommend following at least the first three steps of this tutorial here.
Conclusion
This fully wraps up my article on Setting up Version Control with Git for Unity. I hope you enjoyed it. Comments and critiques are welcome. If I made an error with anything, please let me know and I will edit the information so that it is accurate for those reading this in the future. Tomorrow I will be writing a small tutorial on Basic 2D Player Movement in Unity, so be on the lookout for that if you are interested. Have a nice rest of your day (or evening)!
