Journal 01 — First Setup of Git with Unity
This article is based on a tutorial that is part of the GameDevHQ Professional Unity Developer Program.
- Create a new Unity Project through the Unity Hub. For this example, we will call the project “Version Control”, and select 3D for the type of project. In this example, we open the project with a single 3D cube in the Editor.
2. Sign up for a membership at https://github.com.
One housekeeping item you should consider is the naming convention of your repositories, whether they are designated “main” or “master”. See this discussion: GitHub’s default branch naming convention | by Siddhant Thakur | Mar, 2021 | Medium. For this example, we have selected our “Settings” via the user icon in the upper right of the GitHub site layout. From there, we select “Repositories”, and change the default name from “main” to “master”.
3. Install the Git Command Line interface software from https://git-scm.com/downloads.
There are several installation screens with options during the install process. Keep the default settings and click through to completion.
Open Git Bash.
OR, alternatively, navigate in Windows Explorer to the storage location of your Unity Project. From there, right-click the area and select “Git Bash Here”
For a primer on Git Bash commands, see the following: https://training.github.com/downloads/github-git-cheat-sheet.pdf
4. At GitHub, select “Create Repository”. For this example, we will use “Version-Control-Example” as the name.
Add a “.gitignore” template by searching for “Unity”. This is to prevent certain files used by Unity such as library and temp files from the collaboration process (“pull”, “commit”, “push”), which we will cover later.
5. Link the GitHub repository to the local project. On the Repository screen in GitHub, click the “Code” button to bring up a web server link. Right-click and copy this URL, or click the clipboard icon to copy the link.
in Git Bash, you need to first initialize and track the project. Type: git init.
After initializing, you need to add the webserver link to communicate between the local project and GitHub. Type the following: git remote add origin URL…… (the name “origin” is a typical industry name for your remote server).
Confirm the connection to the origin by entering the following: git remote -v.
6. Time for your first Commit through Git Bash! Remember the following steps as described in the Git Bash cheat sheet:
Pull → Commit → Push
In Git Bash, see commands by typing: git (dash)(dash)help (darn auto-formatting…)
Perform an initial Pull from the Origin with the following command: git pull origin master. You can also type in: git branch, in order to confirm there is only one branch configuration on your repository (more on this later).
7. Now check the status of files in your local project by typing: git status. Files in red are untracked.
Add all the files shown by type: git add . ← Period means “all”. Check git status again.
Now to Commit these files, include a message for the changelog by typing: git commit -m “_____________” ← changelog message in quotations. In this example, we will say: git commit -m “Created new Unity project”
8. Time to Push the revisions to the server. Type: git push origin master
Check the results on GitHub.
As a challenge, try the following: open up the Unity Project in Unity, add an object to the scene, or add a generic C# script, something that changes the scene. Save the Unity Project. Now in Git Bash, repeat the previous steps:
Pull → Status → Add → Commit → Push
As an example, I will add another cube and generic C# script CubeMove and document these changes.
9. Branches — Use of branches is a best practice. See the following diagram from the GitHub Cheat Sheet. Branches can be used to split up the workflow into a developer environment in order to prepare all the changes internally before merging into a final finished project. Or branches may be created for different work groups that are part of a project team (e.g., “Quests” team, “Inventory” team, “UI” team, etc.).
Branches may be created in Git Bash with the following command: git branch ______ ← branch name
To switch to a different branch, use the “switch” or “checkout” statement. In this case, we will switch to the dev branch.
Now while we are in the dev branch, let’s make some changes in Unity. For example let’s add a couple spheres.
Let’s save Unity and add the updates and commit while in the dev branch.
Let’s switch back to the master branch, and look at the Unity Editor again. As you see, those changes made in the dev branch are not shown in the master branch.
10. Merge branches — This function can combine the revisions made in branches. In the example above, we made changes to the dev branch, but these are not visible in other branches. From the example above, let’s merge the changes made in the dev branch to the Quests branch.
And while in the Quests branch, let’s check Unity.
Now let’s make one more change while in the Quests branch by adding in a generic C# script, then repeat the steps described above:
Unity Edits (save) → git add . → git commit → Switch branch to master → Merge other branches → git push origin master
11. Revert — Consider this option if you need to revert your project to a previous state. To see all your previous commits, you can type: git log
The commit instances may be added as their own branch, in order to confirm with the team the correct instance to work from. With this workflow, the work progress is not lost. So for this example, let’s create a branch from the “Add cube and script CubeMove” instance and investigate. To do this, you copy the commit instance tag, and add that as a branch.
Note in the above line for “git checkout”, we are using “-b old-project-state 26f979…” This is an option to rename the long commit tag into a more user-friendly branch name.
12. Reset — Consider this option of if you need to reset the project to a previous state. Note this will wipe the revisions made after the selected reset point. For this project, let’s reset the project to when the project was first created in Unity.
Copy the commit tag and type: git reset (dash)(dash)hard _____ and see the results in Unity.
Now these changes need to be forced onto the Web Server origin. Type: git push (dash)(dash)force origin master
