Git and Unity: A Comprehensive Guide to Version Control for Game Devs

I have been using Git for version control for over 15 years. It's been my constant companion on tiny personal projects, 20-person Unity projects, and even the massive Windows operating system. Git has become the de facto standard for the software industry, and it's growing in popularity for Unity game development.

Git is actually easy to learn if you start from the fundamentals. In this guide, we'll begin with the basics of setting up Git for Unity to track versions of your project. Then, we'll move on to more advanced topics like backing up your project to GitHub, collaborating with a team, and sharing code and assets between multiple projects.

Quick Summary

If you're short on time, here’s the high-level flow for Unity version control:

1. Initialize a Git repository in your Unity project.


2. Add a Unity-specific .gitignore so you don’t commit generated files.


3. Use Git LFS for large assets (textures, audio, video, models).


4. Commit early and push to GitHub for backup and collaboration.

Prerequisites

Before you start, make sure you have:

• A Unity project that builds locally.


• Git installed (CLI tools or a Git client).


• A GitHub account if you want remote backups or collaboration.

Table of Contents

• Quick Summary


• Prerequisites


• Why You Need Version Control for Unity


• What is Git?


• What is a .gitignore?


• How to Initialize a Git Repository for Your Unity Project


• Using Git LFS with Unity To Track Large Assets


• Making Your First Commit


• Useful Git Commands for Unity Developers


• Commit Early, Commit Often


• Branching and Merging


• Asset Conflicts and Merging


• Git Clients: UI for Git!


• Git on the Web: GitHub for Unity Developers


• Pushing your Unity Project to GitHub


• Working with a Team: GitHub Organizations


• Creating Your First Pull Request on GitHub


• Sharing Code and Assets Between Projects: Submodules vs Unity Packages


• Git on a Team: Branching Strategies for Unity


• Automated Unity Builds and CI/CD with GitHub Actions

Why You Need Version Control for Unity

Timmy the Clever Game Developer

Meet Timmy, a talented and passionate game developer. Like many before him, Timmy started his career by working on small projects, handling everything from code to art. Timmy had a clever way of tracking changes to his project. Whenever he made significant changes, he would create a new version of the file, appending a systematic version number to end of the filename. It worked great – GameScene_v0.0.1.unity, GameScene_v0.0.2.unity, and so on.

But as his projects grew in complexity, so did his file naming conventions. Soon, his project folder was littered with files GameScene_v3.6.7_FINAL.unity, GameScene_v3.6.7_FINAL_b.unity, and GameScene_v3.6.7_REALLYFINAL.unity. Finding the right file became a game in itself. Timmy's team was not too happy either, unable to understand which version of Timmy's files they should use.

There must be a better way, Timmy thought.

Timmy Discovers Source Control

One day, Timmy decided enough was enough. He read an interesting blog post which introduced him to the world of version control systems (VCS). Intrigued, Timmy started learning about Git, a popular and powerful VCS.

The more Timmy learned about Git, the more he realized how it could revolutionize his workflow. Instead of manually renaming files and risking data loss, Git could track every change automatically. He could create branches for new features, merge them seamlessly, and revert to previous versions effortlessly. Collaboration would become straightforward, with each team member working on their own branch without conflict.

What is Git?

Git is a distributed version control system (VCS) that allows developers to track changes in their code, collaborate with others, and manage their projects efficiently.

Git was initially created by Linus Torvalds, the creator of the Linux operating system, in 2005. He developed Git to manage the Linux kernel development, and it has since become one of the most widely used version control systems in the world.

Git has been used for solo Unity projects and for AAA games. At Virtual Maker, we use Git for all of our projects.

Basic Concepts

Learning all the concepts in Git can take a bit of time. We'll start with the core concepts that are most important to understanding what you're doing.

In this guide, we’ll illustrate how to use Git with the command line. This is the best way to understand how Git works. Once you've mastered the basics, you can use Git Clients like Fork and GitHub Desktop that offer a graphical interface (if you prefer).

Let's get started.

Choose a Unity project or create a new one. Then, open your terminal or command prompt and navigate to your Unity project directory.

> cd path/to/my/unity/project

Initialize the repository by using the git init command:

> git init

Initialized empty Git repository in /Users/vm/repos/GitTestProject/.git/

This command creates a new subdirectory named .git that contains all of your necessary repository files.

Now, use git status to see what Git sees.

> git status

On branch main



No commits yet



Untracked files:

  (use "git add <file>..." to include in what will be committed)

        Assets/

        GitTestProject.sln

        Library/

        Logs/

        Packages/

        ProjectSettings/

        Unity.Services.Core.Analytics.csproj

        Unity.Services.Core.Configuration.Editor.csproj

        Unity.Services.Core.Configuration.csproj

        Unity.Services.Core.Device.csproj

        Unity.Services.Core.Editor.csproj

        Unity.Services.Core.Environments.Internal.csproj

        Unity.Services.Core.Environments.csproj

        Unity.Services.Core.Internal.csproj

        Unity.Services.Core.Networking.csproj

        Unity.Services.Core.Registration.csproj

        Unity.Services.Core.Scheduler.csproj

        Unity.Services.Core.Telemetry.csproj

        Unity.Services.Core.Threading.csproj

        Unity.Services.Core.csproj

        UnityEditor.UI.csproj

        UnityEngine.UI.csproj

        UserSettings/



nothing added to commit but untracked files present (use "git add" to track)

Git says there are no commits, so nothing is being tracked in version control. Git lists files that could be tracked but aren't as untracked files.

Before we start tracking files, we need to ensure Git doesn't track anything we don't need.

What is a .gitignore?

A .gitignore file specifies which files and directories git should ignore in a project. For Unity projects, this file is crucial because it helps avoid committing all the stuff that Unity will regenerate by itself, like the Library, Temp, and Logs folders.

To make matters worse, each time you edit and commit a large binary file like an image or audio file, the entire file is added to your Git history. This will cause the repo size to balloon, taking much more disk space on each developer's machine than they would need without Git.

Git LFS (Large File Storage) solves this problem by only storing a pointer to the large file into the Git history. The large file itself is stored in a separate database so it doesn't take space in your repository, and only the necessary version is downloaded onto each developer's machine.

Once installed, Git LFS needs to be set up for each user account using git lfs install.

> git lfs install

Updated Git hooks.

Git LFS initialized.

There are two ways to tell LFS which files to track:

• Track specific files.


• Pattern match with the wildcard * syntax.

Important: You need to set up LFS tracking rules before adding the large files to git. Otherwise, they won't be tracked by LFS correctly.

Tracking specific files with LFS

If you're using a web host like GitHub, it's usually best to track specific large files to avoid unnecessary LFS limits and fees.

Track a specific file with LFS using the command:

> git lfs track path/to/MyLargeFile

This command will create or modify the .gitattributes file. You can inspect and edit this file manually.

path/to/MyLargeFile filter=lfs diff=lfs merge=lfs -text

The -text at the end tells Git to treat the file as binary and skip line-ending normalization. The file checked in to Git will be a simple text pointer to the real file tracked by LFS.

The "filter", "diff", and "merge" options are how LFS hooks into Git's operations to download the real file onto your machine.

Pattern matching files with LFS

Usually, large files are of a certain type. For example, maybe you have many videos of .mov format. Track these files with LFS using the command:

> git lfs track "*.mov"

Here are some other file types you may want to track. However, keep in mind that web hosts like GitHub will charge you based on how much LFS data you use.

# Image

*.jpg filter=lfs diff=lfs merge=lfs -text

*.jpeg filter=lfs diff=lfs merge=lfs -text

*.png filter=lfs diff=lfs merge=lfs -text

*.gif filter=lfs diff=lfs merge=lfs -text

*.psd filter=lfs diff=lfs merge=lfs -text

*.ai filter=lfs diff=lfs merge=lfs -text

*.tif filter=lfs diff=lfs merge=lfs -text



# Audio

*.mp3 filter=lfs diff=lfs merge=lfs -text

*.wav filter=lfs diff=lfs merge=lfs -text

*.ogg filter=lfs diff=lfs merge=lfs -text



# Video

*.mp4 filter=lfs diff=lfs merge=lfs -text

*.mov filter=lfs diff=lfs merge=lfs -text



# 3D Object

*.FBX filter=lfs diff=lfs merge=lfs -text

*.fbx filter=lfs diff=lfs merge=lfs -text

*.blend filter=lfs diff=lfs merge=lfs -text

*.obj filter=lfs diff=lfs merge=lfs -text



# ETC

*.a filter=lfs diff=lfs merge=lfs -text

*.exr filter=lfs diff=lfs merge=lfs -text

*.tga filter=lfs diff=lfs merge=lfs -text

*.pdf filter=lfs diff=lfs merge=lfs -text

*.zip filter=lfs diff=lfs merge=lfs -text

*.dll filter=lfs diff=lfs merge=lfs -text

*.unitypackage filter=lfs diff=lfs merge=lfs -text

*.aif filter=lfs diff=lfs merge=lfs -text

*.ttf filter=lfs diff=lfs merge=lfs -text

*.rns filter=lfs diff=lfs merge=lfs -text

*.reason filter=lfs diff=lfs merge=lfs -text

*.lxo filter=lfs diff=lfs merge=lfs -text

Now that the large files are taken care of, let's get back to making your first commit!

Making your First Commit

To make a commit takes two steps. First, we "stage" the changes using the git add command. This command can be used over and over to select which files you want to add to the commit.

The git add . command is a shorthand to stage everything in the current directory.

> git add .

Let's do a quick check to see that Git is tracking with the git status command. Your list of files may be different depending on your project setup.

> git status

On branch main



No commits yet



Changes to be committed:

  (use "git rm --cached <file>..." to unstage)

        new file:   .gitignore

        new file:   Assets/Scenes.meta

        new file:   Assets/Scenes/SampleScene.unity

        new file:   Assets/Scenes/SampleScene.unity.meta

        new file:   Packages/manifest.json

        new file:   Packages/packages-lock.json

        new file:   ProjectSettings/AudioManager.asset

        new file:   ProjectSettings/ClusterInputManager.asset

        new file:   ProjectSettings/DynamicsManager.asset

        new file:   ProjectSettings/EditorBuildSettings.asset

        new file:   ProjectSettings/EditorSettings.asset

        new file:   ProjectSettings/GraphicsSettings.asset

        new file:   ProjectSettings/InputManager.asset

        new file:   ProjectSettings/MemorySettings.asset

        new file:   ProjectSettings/NavMeshAreas.asset

        new file:   ProjectSettings/PackageManagerSettings.asset

        new file:   ProjectSettings/Packages/com.unity.testtools.codecoverage/Settings.json

        new file:   ProjectSettings/Physics2DSettings.asset

        new file:   ProjectSettings/PresetManager.asset

        new file:   ProjectSettings/ProjectSettings.asset

        new file:   ProjectSettings/ProjectVersion.txt

        new file:   ProjectSettings/QualitySettings.asset

        new file:   ProjectSettings/TagManager.asset

        new file:   ProjectSettings/TimeManager.asset

        new file:   ProjectSettings/UnityConnectSettings.asset

        new file:   ProjectSettings/VFXManager.asset

        new file:   ProjectSettings/VersionControlSettings.asset

        new file:   ProjectSettings/XRSettings.asset

        new file:   ProjectSettings/boot.config

Now we can use the git commit command to create a new commit with a meaningful message:

> git commit -m "Initial commit of my Unity project"



[main (root-commit) e1c03d9] Initial commit of my Unity project

 29 files changed, 2717 insertions(+)

 create mode 100644 .gitignore

 create mode 100644 Assets/Scenes.meta

 create mode 100644 Assets/Scenes/SampleScene.unity

 create mode 100644 Assets/Scenes/SampleScene.unity.meta

 create mode 100644 Packages/manifest.json

 create mode 100644 Packages/packages-lock.json

 create mode 100644 ProjectSettings/AudioManager.asset

 create mode 100644 ProjectSettings/ClusterInputManager.asset

 create mode 100644 ProjectSettings/DynamicsManager.asset

 create mode 100644 ProjectSettings/EditorBuildSettings.asset

 create mode 100644 ProjectSettings/EditorSettings.asset

 create mode 100644 ProjectSettings/GraphicsSettings.asset

 create mode 100644 ProjectSettings/InputManager.asset

 create mode 100644 ProjectSettings/MemorySettings.asset

 create mode 100644 ProjectSettings/NavMeshAreas.asset

 create mode 100644 ProjectSettings/PackageManagerSettings.asset

 create mode 100644 ProjectSettings/Packages/com.unity.testtools.codecoverage/Settings.json

 create mode 100644 ProjectSettings/Physics2DSettings.asset

 create mode 100644 ProjectSettings/PresetManager.asset

 create mode 100644 ProjectSettings/ProjectSettings.asset

 create mode 100644 ProjectSettings/ProjectVersion.txt

 create mode 100644 ProjectSettings/QualitySettings.asset

 create mode 100644 ProjectSettings/TagManager.asset

 create mode 100644 ProjectSettings/TimeManager.asset

 create mode 100644 ProjectSettings/UnityConnectSettings.asset

 create mode 100644 ProjectSettings/VFXManager.asset

 create mode 100644 ProjectSettings/VersionControlSettings.asset

 create mode 100644 ProjectSettings/XRSettings.asset

 create mode 100644 ProjectSettings/boot.config

Pay attention to the first line that Git printed out:

[main (root-commit) e1c03d9] Initial commit of my Unity project

main is the name of the branch that Git added the commit onto. e1c03d9 are the last 7 characters of the ID of this commit. If we use the git log command, we can see the full ID and your message.

> git log

commit e1c03d962e7f8e4d1e08f69b6aebbc3e528b5b84 (HEAD -> main)

Author: Alon Farchy <[email protected]>

Date:   Tue Jul 16 15:34:39 2024 -0700



    Initial commit of my Unity project

Useful Git Commands for Unity Developers

Here are some useful Git commands that you might need frequently:

• 
  git status: Check the status of your working directory.


• 
  git add: Stage a file to be added to the commit.


• 
  git reset: Unstage a file so it won't be added to the commit.


• 
  git commit: Create a commit.


• 
  git revert: Create a new commit that undoes everything in a previous commit.


• 
  git log: View the commit history.


• 
  git reflog: View the history of what you did (commit, checkout, reset, etc.)


• 
  git branch: List, create, or delete branches.


• 
  git switch: Switch branches.


• 
  git restore: Update a file to specific version.


• 
  git checkout: Older command to switch branches or update a file to specific version


• 
  git merge: Merge branches.


• 
  git fetch: Download changes from your remote repository.


• 
  git pull: Do git fetch and then merge your branch with any remote changes.


• 
  git push: Upload changes made to your branch to your remote repository.

For a comprehensive list of commands and their usage, refer to the .

Commit Early, Commit Often

If you make a mistake, you can use the commands in this cheatsheet to roll back to an earlier version.

# Unstage a file so it won't be committed

> git reset <path>



# Checkout the version of the file at the latest commit.

> git checkout -- <path>



# Restore the version of the file at the commit before the latest.

> git restore --source=HEAD~1 <path>



# Restore the version of a file at a particular commit

> git restore --source=<commit-id> <path>



# Create a NEW commit that undoes everything in the specified commit

> git revert <commit-id>



# Delete files which are not tracked by Git. Useful when Unity gets in a bad state.

> git clean -xfd <path>



# Move your branch to the target commit without changing your files.

> git reset <commit-id>



# Move your branch to the target commit and discard all your changes.

> git reset --hard <commit-id>



# Shows you the history of what you did (commit, checkout, reset, etc.)

> git reflog

Branching and Merging

Often, you and your team will be working on multiple things at once. This is where branching comes handy. In Git, you are always making commits into a branch. By default, this is the main branch.

From the main branch, you can create a new branch using the git switch -c command.

> git switch -c branch1

Switched to a new branch 'branch1'

> echo 1234 > file.txt

> git add file.txt

> git commit -m "Creating my first commit on branch1"

Let's compare the histories of main and branch1 using the git log command.

> git log main

commit e1c03d962e7f8e4d1e08f69b6aebbc3e528b5b84 (main)

Author: Alon Farchy <[email protected]>

Date:   Tue Jul 16 15:34:39 2024 -0700



    Initial commit of my Unity project

> git log branch1

commit 736c35ada5a09ef54737f12ded8bb83d92cdc9d3 (HEAD -> branch1)

Author: Alon Farchy <[email protected]>

Date:   Sun Jul 21 19:24:54 2024 -0700



    Creating my first commit on branch1



commit e1c03d962e7f8e4d1e08f69b6aebbc3e528b5b84 (main)

Author: Alon Farchy <[email protected]>

Date:   Tue Jul 16 15:34:39 2024 -0700



    Initial commit of my Unity project

You can see that the history of branch1 also contains the history of main, but the main branch hasn't been changed.

We can always go back to the main branch and make a commit there.

Let's try merging branch1 into main.

> git switch main

Switched to branch 'main'.



> git merge branch1

Auto-merging file.txt

CONFLICT (add/add): Merge conflict in file.txt

Automatic merge failed; fix conflicts and then commit the result.

Uh oh. If you've been following these examples, you'll notice that we added file.txt in both branches and gave them different contents. Git doesn't know what you want to do, so it sounds the alarm by calling a merge conflict.

Merge Conflicts

Merge conflicts happen when Git can't automatically reconcile the differences between two commits. This usually occurs when the same line in a file has been changed in both branches. In our case, file.txt was modified in both main and branch1, resulting in a conflict.

When a merge conflict occurs, Git leaves both changes in the file, like so:

<<<<<<< HEAD

4567

=======

1234

>>>>>>> branch1

This notation shows the conflicting sections. Remember that HEAD refers to our current place in history, which is the main branch.

• The content between <<<<<<< HEAD and ======= is from the main branch.


• The content between ======= and >>>>>>> branch1 is from branch1.

To resolve the conflict, you need to edit the file to contain the correct final content. You might decide to keep one change over the other, or merge the two changes together.

Once you're done merging the file, use git add to stage it for the merge commit. When all files are staged, we can use git merge --continue to complete the merge.

> git add file.txt

> git merge --continue

Asset Conflicts and Merging

Merging your code and text files is straightforward, but what about assets? Two people on your team might edit the same image files, audio files, Unity scenes, prefabs, or many other files in your project. This can cause a big problem because these assets are not easy to merge. In the worst case, one teammate will have to redo their work.

Let's address this problem with two strategies:

• How to avoid asset conflicts.


• How to use Unity's YAML merge tool to merge scenes and prefabs.

Before you go further, make sure your Unity project is set to Visible Meta Files and Force Text (Project Settings > Editor). This makes scenes and prefabs readable in Git diffs and greatly improves merge success.

How to Avoid Asset Conflicts

If there's no conflict, there's nothing to merge. Problem solved! But how can you actually avoid conflicts?

Let's take an example scenario. One developer is adjusting the jump parameters of a character by editing fields on the components attached to the character. Another developer is updating the colors and fonts of the main menu. If the UI and the character are both in the same scene, then there will be a conflict on the scene asset.

Taking this strategy to its logical conclusion, you can avoid many asset conflicts by moving every GameObject in the scene into its own prefab.

Hint: Sometimes you'll accidentally edit a prefab in the scene. Oops! Fortunately, Unity has a solution for this. Find the Overrides dropdown on the root GameObject of your prefab. Not only can you see which fields have been edited, but you can also apply those edits to the prefab. Nifty!

While convenient, these references can cause frustrating asset conflicts in two ways. First, they simply create more reasons for you to edit your assets. Second, if these references are between separate prefabs, then you end up having to edit the scene to set these references. This reduces the benefits of breaking the scene up into prefabs.

This problem isn't just an asset problem. It's actually a well known problem in software architecture: how do you get separate parts of your code to access each other? Martin Fowler, a well known software engineer, wrote a : A dependency injection library that is "light and fast".

How to use Unity's YAML merge tool to merge scenes and prefabs.

Ok, so you broke up your scene into prefabs, but now two developers have added new prefabs to the scene. What do you do?

Meet your new best friend: text format. For simple conflicts like a transform position change, you can edit the YAML files directly to merge the changes.

It's also possible for UnityYAMLMerge to do the wrong thing in complicated situations. Suppose one developer unpacks a prefab in the scene, and another developer overrides a value in the same prefab. UnityYAMLMerge will end up keeping both versions of the prefab in the scene.

Git Clients: UI for Git!

GitHub Desktop is a free, open-source Git client developed by GitHub. It is designed to simplify the Git workflow, making it accessible for both beginners and experienced developers.

GitKraken is a cross-platform Git client known for its elegant interface and robust features. It is designed to streamline Git workflows and improve productivity.

Fork is a fast and friendly Git client for macOS and Windows. It focuses on providing a simple yet powerful interface for managing Git repositories.

Git on the Web: GitHub for Unity Developers

So now we know how to use Git for version control. Now we'll learn how to backup your project and start collaborating with a team.

and .

> git remote add origin https://github.com/{org}/{repo}.git

> git push -u origin main

> git clone https://github.com/{org}/{repo}.git

> git switch main

> git pull

git submodule init

git submodule update

{

    "displayName": "Package Name",

    "description": "This package does XYZ",

    "name": "com.{org}.{package-name}",

    "unity": "2020.3",

    "version": "1.0.0",

    "category": "utilities"

}

https://github.com/{org}/{repo}.git

git status

On branch main

Changes not staged for commit:

  (use "git add <file>..." to update what will be committed)

  (use "git restore <file>..." to discard changes in working directory)

        modified:   Packages/manifest.json

        modified:   Packages/packages-lock.json

"com.virtualmaker.servicelocator": {

    "version": "https://github.com/virtual-maker-net/com.virtualmaker.sharedcode.git",

    "depth": 0,

    "source": "git",

    "dependencies": {},

    "hash": "ba0619eac92235362b45e791b70ac2637ce73900"

  },

"com.{org}.{package-name}": "https://github.com/{org}/{repo}.git#0fde24173316721063c9b46ec35fa8cf261e6531"