Accomplish your creative goals using the world's leading real-time development platform, used to create half of the world's games. Jun 21, 2017 If you use GitHub to review diffs (ex., as part of a pull request workflow), you'll notice that changes in Unity-generated YAML files are usually not actionable. You can reduce the clutter they introduce, while preserving the ability to review them as needed, by automatically collapsing the diffs on GitHub.
Unity is awesome. Git isawesome. Wouldn't it be nice if they got along?
Use Unity to build high-quality 3D and 2D games, deploy them across mobile, desktop, VR/AR, consoles or the Web, and connect with loyal and enthusiastic players and customers. This community is being built to help users of all levels gain access to resources, information, and support from other users in regards to anything Unity.
By default, the Unity editor does not work well with Git. To name a fewproblems:
Accomplish your creative goals using the world's leading real-time development platform, used to create half of the world's games. Reduces frustration and makes Git and GitHub workflows more approachable. Benefit: Open Source by GitHub, free for everyone. Luckily, GitHub actually has a built in Unity.gitignore, which is located in a dropdown menu on repository creation! However, if your project folder is nested inside the repository folder (such that your project hierarchy looks like /Repository/UnityProject/Assets/.), you'll need to make a few edits to the given.gitignore.
- Noise: The editor manages hundreds of temporary files. Merely opening orclosing the editor will create, delete, or modify some of these files.Additionally, since it's possible to develop on and build for multipleplatforms, there are many more extraneous files than you might expect to findon, say, a Rails project.
- Broken object references: The editor keeps track of objects with randomlygenerated GUIDs. If these GUIDs are not committed to Git properly (i.e., via
.metafiles), the project may break when you, for example, switch branches.The more you rely on the editor, the more common and potentially catastrophicthese errors are. - Unresolvable merge conflicts: Depending on your settings, the editor willsave some or all of your files in binary format. If you and a team memberhappen to edit the same file independently – a common scenario if you use theUnity editor heavily – you will not be able to resolve the merge conflictwith Git, and will have to use special tools.
- Large files: A typical Unity project requires a number of large binaryassets for 3D models, sounds, images, fonts, etc., which can significantlyslow down your Git workflow and waste storage space.
The solution is straightforward:
- Add Unity-specific .gitignore settings
- Configure Unity for version control
- 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, youshould gitignore common files for macOS and/orWindows.
2. Configure Unity For Version Control
With your project open in the Unity editor:
- Open the editor settings window.
Edit > Project Settings > Editor
- Make
.metafiles visible to avoid broken object references.Version Control / Mode: 'Visible Meta Files'
- Use plain text serialization to avoid unresolvable merge conflicts.
Asset Serialization / Mode: 'Force Text'
- Save your changes.
File > Save Project
This will affect the following lines in your editor settings file:
- ProjectSettings/EditorSettings.asset
m_ExternalVersionControlSupport: Visible Meta Filesm_SerializationMode: 2
- If you're curious, you can read more about Unity's YAML scene formathere.
3. Use Git Large File Storage
Git Large File Storage (LFS) uses Gitattributes totrack large files with Git, while keeping them out of your actual repository.Note that this will only work if you use GitHub or aserver that supports the Git LFSAPI.
To set it up, download and install the Git LFS command line extension asdocumented on the Git LFS site.
You can manually track the file types that you'd like Git LFS to manage, asdescribed in the Git LFS docs. However, given the numerous file types that Unitysupports, you are likely to miss a few.
- Noise: The editor manages hundreds of temporary files. Merely opening orclosing the editor will create, delete, or modify some of these files.Additionally, since it's possible to develop on and build for multipleplatforms, there are many more extraneous files than you might expect to findon, say, a Rails project.
- Broken object references: The editor keeps track of objects with randomlygenerated GUIDs. If these GUIDs are not committed to Git properly (i.e., via
.metafiles), the project may break when you, for example, switch branches.The more you rely on the editor, the more common and potentially catastrophicthese errors are. - Unresolvable merge conflicts: Depending on your settings, the editor willsave some or all of your files in binary format. If you and a team memberhappen to edit the same file independently – a common scenario if you use theUnity editor heavily – you will not be able to resolve the merge conflictwith Git, and will have to use special tools.
- Large files: A typical Unity project requires a number of large binaryassets for 3D models, sounds, images, fonts, etc., which can significantlyslow down your Git workflow and waste storage space.
The solution is straightforward:
- Add Unity-specific .gitignore settings
- Configure Unity for version control
- 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, youshould gitignore common files for macOS and/orWindows.
2. Configure Unity For Version Control
With your project open in the Unity editor:
- Open the editor settings window.
Edit > Project Settings > Editor
- Make
.metafiles visible to avoid broken object references.Version Control / Mode: 'Visible Meta Files'
- Use plain text serialization to avoid unresolvable merge conflicts.
Asset Serialization / Mode: 'Force Text'
- Save your changes.
File > Save Project
This will affect the following lines in your editor settings file:
- ProjectSettings/EditorSettings.asset
m_ExternalVersionControlSupport: Visible Meta Filesm_SerializationMode: 2
- If you're curious, you can read more about Unity's YAML scene formathere.
3. Use Git Large File Storage
Git Large File Storage (LFS) uses Gitattributes totrack large files with Git, while keeping them out of your actual repository.Note that this will only work if you use GitHub or aserver that supports the Git LFSAPI.
To set it up, download and install the Git LFS command line extension asdocumented on the Git LFS site.
You can manually track the file types that you'd like Git LFS to manage, asdescribed in the Git LFS docs. However, given the numerous file types that Unitysupports, you are likely to miss a few.
Instead, feel free to use this sample .gitattributes file, whichcomprehensively accounts for all the file types that Unity currently supports(either natively or via conversion):
A Bonus For GitHub Users: Automatically Collapse Generated File Diffs
If you use GitHub to review diffs (ex., as part of a pull requestworkflow), you'll noticethat changes in Unity-generated YAML files are usually not actionable. You canreduce the clutter they introduce, while preserving the ability to review themas needed, by automatically collapsing thediffs on GitHub.
To do so, just append this to your .gitattributes file:
You can read more about this featurehere.
You should now be able to use Git to version control a Unity project as younormally would:
- Any changes detected by Git will be legitimate, not noise generated by theeditor.
- You will be able to commit your changes to your repo confidently, withoutfearing that the project will suddenly break when a team member tries to fetchit or you switch branches.
- Your large binary files can be tracked without slowing down or cluttering yourrepository.
- Changes to files generated by Unity (such as Scene files) will have diffs thatcan be inspected normally, and merge conflicts can (at least in theory) beresolved manually. Although…
Github Desktop 32-bit Download
Actually, About Those Merge Conflicts…
Manually resolving merge conflicts between Unity-generated YAML files is verydifficult and error-prone. If you followed the steps above and you're usingUnity 5 or later, you can use the editor's SmartMerge (a.k.a, 'Unity YAMLMerge'). There are also various merge tools on the Unity AssetStore.
Using Unity With Github
As a developer, though, I find these solutions somewhat unsatisfying. Theunderlying problem is not that there is a merge conflict, per se, but that atool (the Unity editor) is translating our commands and our knowledge into alanguage (the Unity YAML format) that is difficult to understand, and indeedthat was not really meant to be manipulated directly.
Github Desktop For Linux
Fortunately, a code-centric approach to Unity development (ex., viaZenject) can minimize these kinds ofproblems, while also supporting numerous software development best practicesthat are often lacking in Unity development.
