A safe and accurate .gitignore for #unity3d (Unity5 onwards)

Github has a website for hosting gitignores. I learnt the hard way that they are NOT vetted, they can lose critical data from your project if you use them blindly.

But Unity doesn’t provide a standard gitignore for Unity projects, so people often ask: Well, OK, so what should my gitignore contain?

I’ve screwed it up a few times over last 8 years, but my current approach seems to work well. This may work for you, or not. Either way: read the notes, understand each line, and be sure you know what it’s doing before you adopt this yourself!

Problem summary/recap

Unity creates a LOT of temp files. Some of those can speed up loading time on your computer. But many of these cannot be used on other computers. e.g. Macs make incompatible files from the ones Windows PCs make. Even different Windows PCs can make incompatible versions with each other (off the top of my head: e.g. pre-compiled shaders for your current platform).

Unity also creates temp files in bad locations (e.g. the root) that follow naming conventions of critical source files (e.g. C# projects).

If you want to share your code with other projects, Unity has zero backwards compatibility, and so you MUST maintain complete separate copies of your project for every version of Unity you might ever want to use that code/unitypackage with. In most hobby game projects, you don’t care, this isn’t a problem – but we’ll go with a general solution since it’s actually no extra effort.

Finally: given Unity puts some files in the root, and it creates magic metafiles for every file it can see, you want to keep your files and Unity’s files separate. If you share the root, you’ll never know what it’s safe to delete. And if you put your non-Unity files in the Unity folder, Unity will waste time constantly indexing and interpreting them.

Solution part 1: Folder structure

Here’s the simplest correct structure for a two new Unity projects, one called “Game 42” and the other called “Some Other Game”:

/[My Game Projects]/
[Game 42]/        <- this is the folder you add to git
UnityProjects/        <- this is the Unity project folder
[Some Other Game]/        <- this is the folder you add to git
UnityProjects/        <- this is the Unity project folder

Key points:

  • Each game has its own repository in git (this should be obvious)
  • You do NOT use the Unity folder as the root – you make it a subfolder (this allows us to know, in git, whether a file is a Unity file or not, just by looking at the parent folder)
  • You can have MULTIPLE unity folders per project, one for each version of the Unity Editor
  • Each Unity-folder is named after the Unity version it contains AND after the project; this way you get all the info you need both inside Unity and outside it to know which folder is which, e.g. when deleting files, or packaging them

Solution part 2: .gitignore

Now we build a gitignore that uses its knowledge of Unity to exclude Unity-temp files, but keep all other files. Note the [syntax] in case Unity uses different case in the folder names. I’ve never had this cause a problem, but it’s a clever feature of gitignore and I see no harm in keeping it in. Note that Unity is NOT compatible with case-sensitive file-systems.

# OPTIONAL: if you have huge assets you’re not ready to commit to source-control yet:

# Autogenerated VS/MD solution and project files

# Unity3D generated meta files

# Unity3D Generated File On Crash Reports

Key points:

  • DO NOT EXCLUDE .sln, .csproj etc from your whole project! If you create any DLLs (speeds up your Unity development time, and makes it easier to share code), you NEED those files in source control.
  • …unless they are Unity’s internal ones, in which case: ignore them
  • The “OPTIONAL” line is for when e.g. you add a 4 gigabyte texture pack, and not sure you want to keep it in your project. Before blowing your git-lfs budget, you can keep those files in Assets/UNCOMMITTED, and they will be ignored by git. When you’re ready to keep them in your project, move the folder into Assets. This is slightly tricky because it needs two lines to support the existence of a possibly-empty folder, hence I kept it in.

Leave a Reply

Your email address will not be published. Required fields are marked *