Checklist for committing Unity Assets

Much of the friction surrounding Unity Assets and meta files comes from the way they interact with version control systems.

One of the quickest ways to reduce that friction is to have your team use this checklist each time they commit Assets to version control.

 Pro tip: It’s even easier with a tool

Since originally writing this page we built MetaBuddy, a plugin for Unity to automatically check your commits for meta file problems.

MetaBuddy finds a wider range of problems than this checklist and without manual effort. Find out how much time it saved us here.

By using this list, you reduce the odds of a bad commit breaking references or causing phantom changes for the rest of the team.

What this checklist isn’t…

This checklist isn’t intended as a substitute for understanding what meta files are or how they work. The better your team understand them, the more effective they will be. Understanding meta files and GUIDs is a great starting point for learning more.

 Looking for a quick fix? This checklist is about prevention rather than cure. If you are running into a specific meta file issue and need a quick resolution, the FAQ is a better place to look.

1. Commit both files when adding, deleting, renaming or moving Assets

If you are adding, deleting, renaming or moving Assets (basically anything that involves changing the filename of your asset on disk) you must commit both the Asset file and it’s .meta file together.

For instance, add Assets/Textures/Explosion.png and Assets/Textures/Explosion.png.meta together.

2. If you have changed an Asset’s settings in the Inspector window, commit its meta file.

The settings in an Asset’s Inspector view are stored in its .meta file. If you don’t commit the meta file, you will lose those settings.

 Pro tip: If the Asset is already under version control, and you have only changed its settings then it is fine to commit the meta file on its own.

3. If you have only changed an Asset’s content you don’t need to commit its meta file

Unity stores your Asset’s content separately from its settings. So if your Asset is already under version control and you have only changed its content, then its fine to commit the content file on its own.

For instance, if you have changed the pixels in the texture Explosion by overwriting Explosion.png and the meta file Explosion.png.meta hasn’t changed, then it is fine to commit Explosion.png on its own.

4. Don’t commit changes that alter the GUID in a meta file

Unity uses the GUIDs in meta files to track references between Assets. If you change an Asset’s GUID, all references to that asset will become broken.

 Pro tip: You can use your version control system’s diff feature on the meta file to determine whether the GUID has been changed.

5. Don’t commit empty directories or their meta files

Many version control systems don’t store empty directories, so if you commit them you are effectively just committing a meta file for something that doesn’t exist.

This can become confusing for your colleagues because they will see a meta file without an associated Asset file.

6. If you have changed Assets outside of the Unity Editor, check their names before committing

When you change Asset files outside of the Unity Editor it is possible for the names of the Asset and it’s meta file to fall out of sync. When this happens, settings get lost and references get broken.

If you have changed Assets outside of Unity, double check that the names of your Asset files and their meta files match exactly. Be especially careful with casing.

eg. The Asset file Explosion.png should have a meta file Explosion.png.meta. Unity simply won’t see near-misses like explosion.png.meta, Explosion.PNG.meta or Explosion.meta.

Next steps

Understand the motivation behind the checks on the list by learning how meta files work. Or checkout the FAQ for answers to specific questions about meta files.