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.
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
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.
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