Git with Unity
A developers guide to use Git with Unity projects
Introduction
Git is a version control system that allows us to collaborate and maintain our Unity’s project code. Version control is aimed at supporting the tracking of changes to a project, that is, the reversal of changes made to a project and the annotation of changes introduced to a code base. It is applicable to both technical and non-technical pieces of work. It could be managed using Git and GitHub to share projects, documents and plans.
Git install
- Go to https://git-scm.com/download/ and download the setup file. Install the downloaded file with recommended settings.
- Go to https://github.com/ and create an account (if you don’t have one).
Create Unity project
Create a new Unity project from Unity Hub.
Common Terminologies
Let’s take a look at some of the common terms that we will come across in this article:
Repository:
A unity of storage and change tracking that represents a directory whose contents are tracked by Git.
Branch:
A version of a repository that represents the current state of the set of files that constitute a repository. In a repository, there exists a default or main branch that represents the single source of truth.
Master:
The default or main branch. A version of the repository that is considered as a single source of truth.
To use the analogy of a river, the master is the main stream of a river. Other branches depart from the main stream, just like a distributary would, but instead of not returning to the main stream, the branches rejoin the main stream, just like a tributary would. This process of joining the main stream is referred to as merging.
Reference:
A Git ref or reference is a name corresponding to a commit hash. The references are stored in a files in the .git/refs directory, of a repository.
HEAD:
A reference to the most recent commit on a branch. The most recent commit is commonly referred to as the tip of the branch.
Working Tree:
This refers to the section in which we view and make changes to the files in a branch. The files that are changed are then moved to a staging area once they are ready for a commit.
Index:
This is an area where Git holds files that have been changed, added, or removed in readiness for a commit. It’s a staging area from where we commit changes.
Commit:
This is an entry into Git’s history that represents a change made to a set of files at a given point in time. A commit references the files that have been added to the index and updates the HEAD to point the new state of the branch.
Merge:
Using the analogy of a river, a merge refers to the process through which a tributary joins the main river.
In Git, a merge is the process of incorporating changes from one branch to another. Here, the branch bringing in changes is the tributary, whereas the branch receiving the changes is the main stream of a river.
Workflows:
Workflows refer to the approach a team takes to introduce changes to a code base. A workflow is characterized by a distinct approach in the usage of branches (or lack thereof) to introduce changes into a repository.
Gitflow workflow:
This uses two branches: master and develop. The master branch is used to track release history, while the develop branch is used to track feature integration into the product.
Centralized Workflow:
This approach uses the master branch as the default development branch. The changes are committed to the master branch. It is a suitable workflow for small size teams and teams transitioning from Apache Subversion. In Apache Subversion, the trunk is the equivalent of the master branch.
Feature branch workflow:
In this workflow, feature development is carried out in a dedicated branch. The branch is then merged to the master once the intended changes are approved.
Forking Workflow:
In this approach, the individual seeking to make a change to a repository, makes a copy of the desired repository in their respective GitHub account. The changes are made in the copy of the source repository and then it is merged to the source repository through a pull request.
Navigating GitHub
Version control with Git takes on a distributed nature. The code resides on each local computer where the code base is being worked on, as well as on a central remote point where every individual who wishes to work on the code base can obtain it. GitHub is one such central remote point. GitHub hosts repositories and enables users to obtain, alter, and integrate changes to a code base through Git:
Creating GitHub repository
- Go to https://github.com/ and sign-in with your credentials, then click on Create repository to create a new one.
2. Create a repository with a name and add a Unity git ignore file. This ignore file prevents Unity from collaborating unnecessary files (such as library files and temp files, which we really don’t care to commit) to the project.
3. We now successfully created “Version Control Example” repository on GitHub.
Working with Git
Git Navigation (Git Bash Terminal Application)
- Command “ls” → lists all the available directories in the location.
2. Command “cd [directory name]” → leads us to access the particular directory.
3. Similarly, navigate to the Unity Project folder.
Linking GitHub to local Unity project
In Git Bash terminal, navigate to the project directory and use command “git init” to initialize GitHub repository into the project.
Specify the GitHub URL of the repository using the command “git remote add origin [repository url]”.
Now we have successfully added it to our local project. To verify that, use command “git remote --v ”
Preparing files for commit
Always follow the order of Pull — Add — Commit — Push to avoid errors.
Getting Help
Use command “git --help” to know about the common git commands used in various situations.
Steps to integrate local Unity project with GitHub:
Step1: Pull from the server and integrate with local project.
Then use the command “git pull origin main” to fetch from the server.
The command “git status” gives the current status of the project. It is used to retrieve the details of the files that are untracked, unstaged, or staged. It lists the files in the order of their statuses.
Step2: Add the files content to the server. Use the command “git add .” to add all the files and folders of the project to the server.
Step3: Commit the files using the command “ git commit -m “[message]”.
The “-m” option that is used with the commit command specifies the message we wish to use for a commit.
Step4: Push the local files to the repository on GitHub using the command “git push origin master”.
Now we can see our project and commits in GitHub.
Preparing files for more commits
Modify the Unity project. For example: create a cube, create a “Challenge” script and then save the project.
Look at the status on terminal using the command “git status”.
Now follow the above mentioned steps to integrate the project with GitHub.
Pull origin master and add the files to the repository. Then commit with a message and push to the server.
Git Branches
Steps to create branches and switch between them:
Step1: Create a new branch using the command “git branch [branch name]”
List all the available branches in the repository using the command “git branch”
Step2: Switching between branches
Switch between the available branches using the command “git switch [branch name]”
Using branches with Git
The changes made to the project in a particular branch neither be seen nor edited in other branches of the repository.
For example: if we switch to dev branch then make changes to the Unity project and then add, commit the files in the terminal, those changes will only available to dev branch. If we switch to the master branch in the terminal and go back to Unity, the changes will get reverted.
Once all the changes are made to the dev branch and it is ready for the release, then it can be merged with the master branch using “git merge [branch name]” command.
The following steps shows the usage of branches with Git:
Step1: Switch to dev branch
Step2: Make necessary changes to the Unity project. For example, add a “DevBranch.cs” script.
Step3: Check the status in the terminal, then add and commit the files with a message to the repository.
Step4: Verify the changes
If we switch to master branch and go back to Unity project, the changes get reverted.
Step5: Merge both branches
Step6: Push the changes of individual branches to the server using push command.
Reverting or Resetting by branch
It is possible to go back to the previous versions of the project where we created commits.
Check the log of the branch by using the command “git log”
Use the command “git checkout [log ID]” to revert our project to that particular state to make any further modification and then can be switched to original branch.
It is also possible to create branches at that particular log state using the command “git checkout -b [branch name] [log ID]”
Reset project to previous state
“git reset --hard [log ID]” command is used to hard reset the unity project to that particular log state by force pushing it to the branch using the command “git push --force origin [branch name]”
This is a dangerous and risk taking factor to the project which cannot be undone. Hench it is advised to regularly branch and consider keeping the changes to the repository before hard resetting the project.
I hope you find this article in handy with your projects. Keep in mind your strategy and constant communication with your teammates as one of the most crucial factors in using Git.
Do you have other useful tips? Share your best practices in the comment section below.
