How to Use Github With Unity

Are you attempting to use Unity with Git/GitHub?

If this is your first time, it can be quite challenging. By default, Unity generates many binary files that Git cannot merge without conflicts. Fortunately, Unity offers some helpful settings that allow most of these binary files to be saved as text files, making them mergeable! Moreover, it’s crucial to have a proper .gitignore file to prevent committing the numerous files that Unity automatically creates. Let’s discuss these two aspects!

.gitignore

The first step is to set up your repository. If you’re unsure about how to do this, you can refer to the wiki article on GitHub for guidance.

Before you begin adding your Unity project to the repository, it’s crucial to create a proper .gitignore file. Fortunately, GitHub offers a pre-configured Unity .gitignore that you can find in a dropdown menu when creating a repository!

However, if your project folder is located within the repository folder (for example, if your structure looks like /Repository/UnityProject/Assets/…), you’ll need to make some adjustments to the provided .gitignore. Below, I’ve included links to both the standard Unity .gitignore and the modified version, so you can easily see the differences and download the edited one if needed.

Edited Unity .gitignore

This is the revised version of the Unity .gitignore file. The only modification I’ve made is adding asterisks before the various directory paths, which enables the .gitignore to effectively navigate to your files.

You might need to make additional adjustments to the .gitignore based on your specific project requirements, but this edited version should meet most of your project’s cleanliness needs.

Key Points:

• Standard Unity .gitignore: Suitable if your main Unity folder is set as the repository folder (e.g., /repository_name/Assets/…).
• Edited Unity .gitignore: Ideal if your Unity project is nested within the repository (e.g., /Repository/UnityProject/Assets/…).

Note: For better readability and convenience, it may be beneficial to keep the repository folder separate from the Unity folder itself (for instance, if you want to create a folder for 3D models in preparation for proper importing). Ultimately, the choice is yours!

After the .gitignore

Now that you have your .gitignore file set up and committed to the repository, it’s time to configure your Unity project! Feel free to clone the repository to your computer using any method you prefer.

Next, let’s create the project. Make sure to create it within your repository folder in Unity.

Once you’re in Unity, navigate to the Editor Settings under Project Settings. On my Mac, you can find this by going to Edit -> Project Settings -> Editor. Here, you’ll see several dropdown options in the Inspector. You need to adjust two settings:

1. Version Control: Set to Visible Meta Files
2. Asset Serialization: Set to Force Text

We’ll discuss this further later.

After making these changes, your project will be all set! The .gitignore file will exclude everything that Unity generates automatically, resulting in significantly fewer binary files.

Binary Files to Text Files

Why are binary files problematic? For starters, they cannot be merged at all. Git excels at automatically merging text files, provided that the two users haven’t modified the same lines. However, due to the nature of binary files, Git cannot determine if different users have altered separate sections of such files.

This issue frequently arises with Unity scene files, which have a .unity extension. If two users attempt to work on the same scene simultaneously, like your main scene, a merge conflict will occur. In the case of binary files, one user’s changes will always be lost; there’s no way to avoid this. In contrast, with text files, there is a chance for recovery.

Dealing with Conflicts

Nonetheless, this scenario is not guaranteed. Unity undertakes significant behind-the-scenes work to generate these files, which means that alterations that appear non-conflicting might actually lead to conflicts. So, what steps should you take when conflicts arise?

You have two choices: either manually merge the files or select one file to proceed with. The first option theoretically allows for both users’ changes to be preserved. However, particularly with text files generated by Unity, it can be extremely challenging, if not impossible, to decipher the meaning of the various modifications. If you’re still intent on making this work, feel free to refer to the article on merge conflicts in the main GitHub wiki for more guidance on manual merging.

In most cases of merge conflicts involving Unity, you’ll likely prefer to proceed with just one version. This topic is also covered in the GitHub wiki, but I’ll briefly outline it here for your convenience.

Handling Merge Conflicts: Step-by-Step

When dealing with merge conflicts, especially with Unity projects, follow these steps using the Git terminal or shell:

Step	Command	Description
1	git status	Identify the specific conflicts. Conflicting files will appear in red with details of the issues.
2	git checkout –ours path/to/file or git checkout –theirs path/to/file	Replace the specified file with either your version (–ours) or the incoming version (–theirs).
3	git add .	Stage all detected changes in the repository for commit.
4	git commit -m “Merge Conflict Resolved”	Create a commit with the specified message to finalize the merge.
5	git push	Upload your commit to GitHub, similar to syncing in GitHub Desktop.

Recommendations:

• Prefer –theirs: Generally safer if you’re aware of the changes being pulled in.
• Team Consultation: If unsure, consult your team to clarify conflicting modifications.

After executing all these commands, return to the GitHub Desktop client and sync once more to ensure everything has been processed correctly.

Aside: Meta Files

Another common issue you may encounter involves .meta files. Unity utilizes these files during the import process to organize assets. They are particularly important for sprites, as they hold information on how spritesheets are divided and how the editor should display these sprites, among other details. Each .meta file records data such as when the file was imported or created. Consequently, if different users generate these .meta files at various times for the same asset, a merge conflict can arise.

The primary challenge with these merge conflicts occurs when users make changes without fully understanding them. Since .meta files are text-based, Git allows users to manually merge the text by adding >>>>>>>HEAD, among other methods. This can create significant confusion for Unity and may disrupt any changes that the .meta files were tracking. To address this issue, it’s essential to educate your team about the purpose of .meta files and the importance of properly resolving conflicts by merging the files correctly (or using git checkout).

Lastly, regarding .meta files: to create a folder in the repository through Unity, the folder must contain at least one item. In other words, Unity will generate a .meta file for a folder but won’t actually create the folder until there is a file inside it. I typically add a placeholder file to each of my folders to ensure Unity creates the folder and commits it to the repository. Otherwise, you might face initial merge conflicts due to multiple users creating folders with the same name.

Conclusion

That’s all there is to it! Those are the main issues you might face when using Git/GitHub with Unity. It’s likely that you’ll come across additional challenges, particularly related to GitHub.