/Unity-Git-Config

For maintaining exemplar git configuration files for Unity3d projects hosted on Github

Primary LanguageShell

Unity Github Config

We've put together some git configuration files to cover the majority of Unity/Git use cases. If you set these up at the start, they should prevent your repos from filling up with cruft. These config files ensure that all large files are tracked by git lfs & that your changes are diff'd appropriately, while the pre-commit/post-merge hooks ensure that meta files stay properly in sync. They also insure you against accidentally trying to upload a >100mb file to github, and ending up with a sad unresolvable local repo.

This process has 4 phases & some prequisites. Please make sure to complete all phases before starting work on your project.

  1. Prerequisites
  2. Configure Unity for Git
  3. Create and Configure Your Repo
  4. Install GitLFS
  5. Invite Teammates

Git Primer

Want a primer on git?

How about a cheatsheet?

Setup Instructions

Prerequisites

Unity 2017 or newer. Tested up to Unity 2018.3.

  • Mac: Git installed either through Xcode command line tools, or from here: http://git-scm.com/download/mac
  • Windows: Git installed using GitForWindows: https://gitforwindows.org/ Note that other windows git installs that don't include gitbash will cause the pre-commit & post-merge hooks to fail, negating many of the key benefits of this setup.

Configure Unity for Git

  1. Create a new unity project.

  2. Open the editor settings:

    Edit > Project Settings > Editor

  3. Force visible .meta files (this will ensure script execution order & object references are maintained)

    Version Control / Mode: “Visible Meta Files”

  4. Force text serialization (this will ensure you can merge & properly diff your assets)

    Asset Serialization / Mode: “Force Text”

  5. Save changes

    File > Save Project

Create and Configure Your Repo

  1. Create a new github repo with the same name as your Unity project. Don't select the default Unity .gitignore, we'll be importing our own later.

  2. Clone the repo to the Unity project folder you created in "Configure Unity for Git".

    If you can't see the /.git/ folder, make it visible by following these steps for Windows or these steps for Mac.

  3. Download the .gitconfig, .gitignore, and .gitattributes file from this into the root of the local repo you just cloned, ie into the folder <your_repo>/.

  4. Edit .gitconfig with a text editor, replacing <path to UnityYAMLMerge> with the location of your Unity install's merge tool (note that these locations can vary if you picked a different install folder during unity install. Also note that you will need to edit this file again if you upgrade Unity & choose a different install location.)

    On Windows it's usually: C:\\Program Files\\Unity\\Editor\\Data\\Tools\\UnityYAMLMerge.exe or C:\\Program Files (x86)\\Unity\\Editor\\Data\\Tools\\UnityYAMLMerge.exe (double slashes are necessary as escape characters).

    On Mac it's usually: /Applications/Unity/Unity.app/Contents/Tools/UnityYAMLMerge.

    This merge tool will try to merge or resolve conflicts within .prefab, .scene, and other unity asset files. If it can't do it automatically, your default merge tool will open & you can manually select which changes to include.
    Always open any merged unity assets & confirm the merge worked before pushing the merged assets. For more info, check this git hub post or this blog post.

  5. Copy the contents of your Unity project into the new folder.

  6. Commit these changes to your new repo & push. Your new project should look like this on Github:

(Keep scrolling, you're not done yet!)

Install GitLFS

  1. Download & install git-lfs from https://git-lfs.github.com/. If you've already installed git-lfs, proceed to step 2.

  2. Open a command prompt, terminal, or gitbash window.

  3. Navigate to the folder containing your git repository & execute: git lfs install

  4. That's all you need to do, as tracking the appropriate files in lfs is taken care of by the .gitattributes file. If you're already familiar with git, you might consider reading this intro to git-lfs, as working with it varies from vanilla git quite a bit.

  5. Download the pre-commit & post-merge scripts. Enable them in your repo by moving them into the folder <your_repo>/.git/hooks/. These will ensure that meta files stay in sync. It will also alert you if you attempt to commit a >100mb file, which github will reject. It will reject the commit, allowing you to revise it to remove or reduce the size of the offending file(s). These scripts have to be installed individually on each computer you clone the repo to. Please ensure your teammates have installed these as well.

  6. On OSX, you must make these hooks executable by chmod +x. https://support.apple.com/guide/terminal/make-a-file-executable-apdd100908f-06b3-4e63-8a87-32e71241bab4/mac

Invite Teammates

  1. Make sure they've all installed git lfs!

  2. Add them to your repo.

  3. Help them clone the repo, copy the pre-commit & post-merge scripts into /.git/hooks/, and setup the .gitconfig file for their system (steps 3-5 of Create & Configure Your Repo).

Usage and Errors

Now that you have these hooks installed, they'll automatically stop you if you try to commit files that might mess up your project. There are a few ways this can happen.

Attempt to Commit File >100MB

If you try to commit a file that's bigger than 100MB, you'll see an error like this one:

Commit failed with error 0 files committed, 1 file failed to commit: testing
Assets/big.pdf is over 100MB.
Can't commit, fix errors first.

Resolve this error by reducing the size of the file. For audio or visual assets, try splitting them into smaller parts or compressing them. For unity .scene files, try to reduce the scene size by dragging elements out of the scene and into prefabs.

Failure to Commit Metafile

If you try to commit an asset without a corresponding metafile, you'll see an error like this one:

Commit failed with error 0 files committed, 1 file failed to commit: testing . Error: Missing meta file.
Asset Assets/LensFlare.flare is added, but Assets/LensFlare.flare.meta is not in the git index.
Please add Assets/LensFlare.flare.meta to git as well.

Resolve this error by adding the corresponding .meta file to your commit.

Failure to Add Corresponding Metafile to Gitignore

If you add a file or folder to the .gitignore, but don't add the corresponding .meta to your .gitignore, you'll see an error like this one:

Commit failed with error
0 files committed, 3 files failed to commit: testing
LensFlare.flare
LensFlare.flare found in .gitignore but not the corresponding meta file! Please add LensFlare.flare.meta to .gitignore .

Resolve this error by editing your .gitignore by adding the .meta file to it.

Always exercise caution when adding to your .gitignore: it's not a tool for resolving bad commits (see the troubleshooting section for help resolving issues with commits). Never add .meta files to the .gitignore without also adding the file associated with that meta file to the .gitignore. Adding files to your .gitignore will result in them not being backed up & nor shared with your collaborators.

Troubleshooting

Did everything above & still managed to run into a problem? Here are some of the best resources for learning how to restore your repo.

Additional Information

Want more info on how we built these config files & hooks? Here's some of the docs & posts we read when building this: