Uloop Verify Project

uloop verify-project

Check the project's files the way Unity reads them on its next import, without starting Unity. When Unity opens a project with these problems, it silently gives assets new GUIDs and deletes orphaned .meta files, which breaks references in ways that cannot be undone. Run this first and fix what it finds while the old GUIDs still exist.

When to use

• After adding, moving, renaming, copying, or deleting assets, especially from a script or another branch
• After a merge or rebase that touched Assets/, Packages/, or ProjectSettings/
• Before committing
• Before opening the project in Unity

Usage

bashCopy code
uloop verify-project
uloop verify-project --project-path <path>

Exit codes:

• 0: nothing found
• 1: problems found (the report is still printed on stdout), or the check could not run (an error envelope on stderr and nothing on stdout)

Checks

What is checked

• .meta files under Assets/, under every embedded package (a folder directly under Packages/ with a package.json file), and under every local package the manifest lists as file: (a relative path is resolved from Packages/). A folder inside another of these is checked once.
• Names Unity hides are skipped and need no .meta file: names starting with ., names ending with ~, cvs in any case, and files with a .tmp extension in any case.
• Plugin folders ending in .bundle, .framework, .xcframework, .plugin, or .androidlib (any case) need their own .meta file, but nothing inside them is checked: Unity imports such a folder as one plugin, so the files inside are not checked whether they have .meta files or not.
• Symbolic links need a .meta file but are never followed.
• A .meta file pairs with its asset by exact name, letter case included, so the result is the same on every OS. An orphaned .meta file is not checked further, because Unity deletes it.
• Conflict markers are searched in every file of those folders (.meta files included), every file under ProjectSettings/, and Packages/manifest.json and Packages/packages-lock.json. Only the first block of each file is reported. A file with a NUL byte in its first 8000 bytes is treated as binary and skipped.

Output

JSON on stdout:

• Success: true when nothing was found
• ProjectRoot: the checked project
• FindingCount: every problem found, including those left out of Findings
• CountsByCheck: the count for each of the six checks, always all six
• Findings: each with Check, Path, and Message, plus Line for CONFLICT_MARKER and GUID and RelatedPaths for GUID_DUPLICATE. Path is /-separated and relative to the project, or absolute for a local package outside it. Sorted in the order of the table above, then by path. At most 100 findings of each check are listed.
• Truncated: true when a check had more than 100 findings
• ScannedRoots: the folders whose .meta files were checked
• MetaFileCount: how many .meta files were checked
• Message: one-line summary

Notes

• A file you just created has no .meta file until Unity imports it. Run uloop compile first, or treat META_MISSING on brand-new files as expected.
• After a fresh clone, an empty folder that git does not track leaves its folder .meta file as META_ORPHAN. Delete that .meta file, or add a file to the folder so git tracks it.
• Run it while Unity is idle. Files Unity is writing at that moment can be reported, and a file Unity deletes during the check makes the command fail; run it again once Unity is idle.
• Not checked: GUID collisions with packages in Library/PackageCache, folders hidden only by the Windows hidden attribute (they are reported as META_MISSING), and package folders under Packages/ that are symbolic links.
• It only reads files and works whether Unity is open or closed.
• If uloop answers that verify-project is an unknown command, or that it "is handled by the global uloop dispatcher", the installed uloop is older than this command: run uloop update.