Championhunter738

In this how-to guide we show you how to set up a Unity project for version control using GitHub.

Pre-requisites

To follow along with this guide you will need the following:

• Unity

  You can download and install different versions of Unity using Unity Hub which is available here. It is worth getting a recent version of Unity because they have better support for version control. We used 2019.3.3f1 to write this guide.

• Git Client

  We’ll be using the command line client in this tutorial. You download it, or alternatively a visual client, here

• GitHub account

  A free account is fine to get started with. You can sign-up here.

Unity files seem to fall into this category. You can find sources on the web, there are different guides to use git efficiently in Unity projects. This is one, updated recently. And a search here on SO on appropriate tags is quite fruitful. Don't hesitate to compare different settings to choose what best suits your specific context. Get the GitHub for Unity package from GitHub and speed up your game development process. Find this & other Version Control options on the Unity Asset Store. Sprint into Spring Sale is on: Get 50% off top assets and score extra savings with coupon code SPRING2021. Unity script for simple object rotation. GitHub Gist: instantly share code, notes, and snippets. GitHub authentication is embedded in Unity, including 2FA. And with a click of a button, you can quickly initialize your game’s repository. Use the GitHub for Unity Extension Get off of the command line and work exclusively within Unity by downloading and installing the GitHub package! Use Git Large File Storage; 1. Add Unity-specific.gitignore Settings We recommend GitHub’s Unity.gitignore template. In addition, depending on the platforms you intend to use for development, you should gitignore common files for macOS and/or Windows. Configure Unity For Version Control With your project open in the Unity editor: Open.

Step 1 - Create the project

• Open Unity Hub
• Click the Add button in the top right.
• Choose the version of Unity. (we used 2019.3.3f1)
• Select the path where your new project’s directory will be created.
• Give your project a meaningful name.
  • It’s best to avoid spaces and special characters as Unity will create a directory from the project name.
• Click Create to create your project.

Step 2 - Project settings for version control

Github For Unity Command Line

There are two important settings that your Unity project needs to have before you use it with git:

• Version Control Mode set to Visible Meta Files
  • Instructions here.
• Asset Serialization Mode set to Force Text
  • Instructions here.

In modern versions of Unity, these settings are the default, but it is worth checking them if your project originated in an older version of Unity.

Step 3 - Initialize the project for git

• Open a Command Line Window (PC) or a Terminal (Mac)
• cd into your new project’s directory
• Run git init to add git conifiguration to your project
  • This creates a hidden folder .git within the project directory to hold the files git needs to version control the project
• Run git status to see how git sees our project. You should see something like this:

Step 4 - Take a look inside your new project

We can see that our new project directory contains a bunch of directories that Unity has created for us.

These directories contain files falling in to one of three broad categories:

Source files

These directories contain the files that your project is built from.

Examples of source files are the Scenes, textures, models, source code, etc. stored in the Assets/ directory.

Transient files

These files are created by Unity as you use it to create and build your project.

Typically they don’t contain anything that can’t be created from the source files above. Examples are the asset cache in Library/ and the log files in Logs/

Local settings

These files contain settings that are local to you and your machine.

These files contain things like your personal preferences for window layout and the like. Examples are files in the /UserSettings/ folder.

Step 5 - What to commit? What to ignore?

Key point: This is one of the most common causes of confusion when setting up a Unity project for use with a version control system.

In order to collaborate on your project, your teammates only need a subset of the files from the project directory. Specifically, the Source files in the first category above.

Everything else can either by re-created from the source files or is of no interest to anyone but you. We need to tell Git to ignore these files so that they never get considered for version control.

Adding .gitignore

We do this by adding a file called .gitignore containing details of the files that should be ignored.

Once we have created this file, we’ll add it version control so that our team mates can share it. That way everyone will have the same “clean” view of the project that excludes all of the transient and local setting files.

GitHub provide a great template .gitignore file for use with Unity projects here

If you have curl installed you can download the template directly into your project directory like this:

Alternatively, create a new file with your text editor, paste in the contents of the template from the above URL and save it as .gitignore in the root of your project directory.

Heads up: Use GitHub’s Raw button to get a view of the file that is suitable for copy and pasting.

Step 6 - Checking our .gitignore

Now, when we run git status again we should see only the files and directories that need to be added to git, with the rest being quietly ignored thanks to our .gitignore file.

The directories containing transient and local setting files (like Library/) have been omitted.

Step 7 - Staging files for commit

The process of saving a set of changes to git is known as a commiting. We’re now ready to commit our project for the first time.

The first thing we have to do is tell git which files we want to commit. This is known as staging the files for commit.

We run the git add . command to stage files for commit. In this case we specify “.” to add everything in the current directory.

Once you have staged the files, run git status to see what has happened.

You’ll see that everything in our source directories have been moved to the Changes to be comitted section at the top of the output.

Step 8 - Committing the staged files

Now we specified which files we will be committing by staging them, let’s go ahead and commit them to Git with:

The -m option lets us add a message describing what we have committed.

It is a good idea to use meaningful commit messages as they will help you understand the history of your project and diagnose problems in the future.

Pro tip! Commit messages don’t need to be too wordy. For instance, you don’t need to repeat all of the files that you have changed as git takes care of that.
Conversely, they should contain enough information to allow you and your teammates to understand what each commit contains.
Lazy messages like “add stuff” will be really frustrating if you ever have to revisit the commit in the future.

Step 9 - Inspecting our first commit

Now that we have committed our files, let’s run git status again to see where we are at.

Where did all our changed files go? They have been committed to our local git repository.

But if you do a directory listing we’ll see that the files are still there in our project directory.

The key thing to learn here is that git status only shows the files that are different from our git repository.

Now that our changes have been committed, the repository has the same contents as our project directory. Because they match, there are no changes for git to show us.

Commit history

Git keeps a log of all changes that we ever committed to the repository. That’s every change, to every file along with the commit message.

This log gives a complete history of how our project evolved over time. Let’s take a look at it with git log --name-only

There’s our commit, along with it’s description and the files we committed.

Later, when we push the repository to GitHub, we will be able use GitHub’s web user interface to browse through our commit history in a much friendlier way.

Commit hash, our commit’s unique identifier

The long hexadecimal number above starting abc2f... is the hash for the commit.

This number uniquely identifies the commit. This is useful when we want to refer to the commit in future, for instance if we want to undo it, remind ourselves of what files it changed or send it to colleague for review.

Step 10 - Sharing our work via GitHub

Now that we have our project in a local git repository, it is time to share it with the team. So far we have been working entirely locally. None of our work has left our machine.

To share our work with the team we need push the changes that we have committed to our local git repository to a server or service where our team mates can get hold of them.

Shared repositories like this are known as remote repositories and sending changes from our local repository to the remote repository is known as pushing.

The GitHub service allows us to create remote repositories that are stored in the cloud where they can be accessed by our team mates.

While we are using GitHub here, there are plenty of other git services available, each with their own strengths and weakness. Some you might want to take a look at are GitLab, BitBucket and Microsoft Azure Repos.

Sign-up to GitHub

The first thing you will need is a GitHub account. GitHub offers a variety of plans, ranging both free and paid.

At the time of writing the free plan is a good place to get started for the purposes of this guide, but you should keep your eye on the paid plans if you are planning to use the repository on a larger project.

The paid plans give you the ability to collaborate with a bigger team. They also give you additional storage space if your project includes a lot of large assets.

Sign up to GitHub here.

Step 11 - Create a repository in GitHub

Once you are signed up to GitHub, we need to create an empty repository to push our local changes to.

GitHub provide a great set of instructions creating a new repository here

Attention Watch out for the visibility setting when creating your new repository.
GitHub’s default for free accounts is to make the repository publicly visible which means anyone on the internet can access it.
If this isn’t what you want, choose the Private option so the repository can only be seen by people that you invite.

Step 12 - Setup SSH keys to access GitHub

The git client is capable of using a variety of different protocols when connecting to a remote repository like the one we just setup in GitHub.

Which one you use is up to you, but we have had good results with SSH as it offers a decent balance between simplicity, security and flexibility.

GitHub show you how to setup SSH access to your GitHub repositories here. The key thing to note down is the repository URL at end of the creation process.

It should look something like this:

Step 13 - Connect your local repository to GitHub

Once you have SSH access to GitHub configured, you need tell your local repository about the remote repository. By doing this, you are letting git know where to look when you push or pull changes from the local repo to the remote one.

Go back to your command line session and after checking that you cd‘d into your project directory, run this command to configure the remote repository, substituting the URL for your own repository.

In our case it looked like this:

Step 14 - Push your local changes to GitHub

Now that we have the local repository connected to the remote one, let’s try to push our local commits to GitHub with:

Unfortunately we are seeing an error here rather than a successful push.

Git is telling us that while it knows where to find the remote repository it doesn’t know which branch in that repository corresponds to the “master” branch in our local repository.

Git helpfully tells us how to configure the remote branch in the error message.

For simplicity it is a good idea to follow git’s default behavior and use consistent names for your local and remote branches. For example, the branch “master” in your local repository will push to the branch “master” in your remote repository.

Let’s accept Git’s suggested configuration:

Now if we go back to the project in GitHub, we’ll see the files from our first commit like this:

We will also see that we have a single commit, showing:

• The commit message.
• The files that were changed in the commit.
• The commit hash.

Pro tip Notice how Github doesn’t show diffs for .meta files by default.
This is because Unity is supposed to manage them us and we shouldn’t need to look into them.
This is the case most of the time but occasionally you may need to look inside them as we’ll see in our deep dive into meta files.

Step 15 - Cloning a clean copy from GitHub

Before you start inviting your team mates to the project repository in GitHub, let’s verify that it is complete and ready for use.

To do that we will pull down a clean copy of the repository from GitHub in to a new directory on our machine. Git calls the process of pulling a repository for the first time cloning the repository.

Doing a fresh clone mimics the experience that our team mates will have when they first start using the repository from GitHub.

First, leave the directory your original project directory:

Then, clone a copy into a new directory like this, where DESTINATION_DIRECTORY is the name of a new directory that git will clone into.

I used coworker-unity-meta-file-test so my fresh clone will end up a directory with that name.

Note Normally, your team mates would omit the second argument and git would clone into a directory named after the repository.

Unity3d With Github

Step 16 - Test our fresh clone

Now cd into the directory containing our new clone and verify that everything is there:

We can see the three principle directories Assets/, Packages/ and ProjectSettings/ which looks positive.

Step 18 - Open the project in Unity

Now let’s load up our new copy into Unity and make sure that everything works.

Go to Unity Hub, add the fresh clone directory and open it.

Note: You will probably see Unity take a while “importing assets” while it repopulates its local caches from the source files in the project.
This will recreate the Library/ directory in your project, but you won’t see that as a change because we excluded it from version control above using the .gitignore.
You only tend to see see this delay when you first open a fresh clone of the project. Unity will then work from your local caches, making subsequent opens much quicker.

Once Unity has opened the project, hit Play and verify that everything behaves as expected.

If doesn’t fix up any missing files or errors before, adding them to version control with the process that you will be using a lot from here on in:

• Stage the changes to commit - git add <FILES TO ADD>
• Commit the change - git commit -m '<YOUR MESSAGE>'
• Push the changes to GitHub - git push

Github For Unity Clone

Next steps

Now that your project is safely version controlled in GitHub, teach your team how to commit changes to it confidently with our Unity Asset commit checklist.

GitMerge for Unity is a free, open source Unity Editor tool that allows you to merge scene and prefab files. This solves the main problem you currently get when using Git to work with Unity.

About

Unity offers a few solutions for collaborative teamwork. These do not necessarily stick to the standard you're used to. So... why not use Git?

You'll have to take these two things into account in order to get started:

1. Setup a good .gitignore, like this one.
2. Get yourself a mergetool for scenes and prefabs.
   That's where GitMerge for Unity is supposed to come in.

GitMerge for Unity is licensed under the GPL2.0 license.

How to install

To use GitMerge for Unity, go to the project page and clone the repository into your Assets Folder.

Next, you make sure that Git doesn't try to merge scenes and prefabs automatically, since this usually leads to broken files with Unity scenes and prefabs.

You have two ways to do that. The first one is to make sure that 'Asset Serialization' is set to 'Mixed' or 'Binary'. Unity will save scenes and prefabs as binary files and Git won't touch them.

If you want your files serialized as YAML files, you can alternatively add a .gitattributes file that tells Git to handle said filetypes as binary files, even though you want Unity so save them as YAML files.
That .gitattributes file could look like this:

That's it, you're ready to go!

How to use

Start merging

GitMerge for Unity comes as an opt-in merge tool. It is not integrated into Git as an automatic merge tool since merging scenes and prefabs is something you'd never want to have done automatically.

First off, you create your merge conflict the way you usually do. Once you're in Git's MERGING state, open the GitMerge window in Unity (Window → GitMerge).

This is what a scene merge situation can look like.

The BoxCollider component of the 'Cube' GameObject has been automatically merged to the default setting ('keep it').
The user has decided to use 'their' version of Transform.LocalPosition, but 'our' version of Rigidbody.Interpolate and BoxCollider.IsTrigger.
The other two conflicts have not been addressed yet.

Merge a scene

To merge a scene, open it the usual way. Then, in the GitMerge Window, click 'Start merging this scene'. When there is an active merge conflict, the tool will find the differences between the currently opened version of the scene and 'their' version.

You will then get a list of so called 'MergeActions' in the tool window. Each MergeAction solves one point of conflict between the two scenes.
To do this, you will be offered two to three options every time:

• Use 'ours' (left side)
• Use 'theirs' (right side)
• Use new (center, when applicable)

You can choose to click the left button to use our version, the left button for their version, or enter a new value in the middle. Either way, the MergeAction line will turn from red (unmerged) to green (merged). MergeActions that have been automatically merged to a default (like keeping a Component that 'their' version doesn't have) are marked yellow.

You can, of course, continue to edit the scene in a normal way during merging. It is not recommended to delete GameObjects that might be part of a MergeAction though.

When all MergeActions are flagged as merged, you can click on 'Apply merge'.
The scene will be saved and marked as merged for git. Since there could be more merge conflicts, this will not automatically commit.
You'll have to commit your merge manually at some point from now on.

Merge a prefab

Merging a prefab pretty much works like with a scene.

While in a merge conflict, open the 'Merge Prefab' tab and drag your prefab into the field.
A new scene will be opened. This scene contains an instance of said prefab. You'll get the same type of list you already know from scene merging. Merge your conflicts and see the result on the prefab instance.

When you hit 'Apply merge' when done, you will be returned to the scene you were in before. The prefab file will be added to the Git stage, but remember that you'll have to commmit the merge yourself.

Active development

GitMerge for Unity is an open source tool that is being actively developed. You can head over to the project page, check out issues, fork, and make pull requests.
If you find a bug or something to improve, but cannot fix/implement it yourself, feel free to tell me about it.

To see what's up next, have a look at the project's issue page.