From 58a258273b95c1f5289f2aefc28bc1b64d2279d0 Mon Sep 17 00:00:00 2001 From: BeardedPlatypus Date: Sun, 8 May 2022 10:49:32 +0200 Subject: [PATCH] docs(README): update readme with additional information --- README.md | 43 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index dcffc87..9f79f4b 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,43 @@ # unity-metafiles-teamcity-check -Python script to verify .meta files in a Unity project on TeamCity + +A simple script, [verify_metafiles.py](verify_metafiles.py), to verify the validity of +`.meta` files on TeamCity. It gathers all relevant files, and verifies that each asset +has a corresponding `.meta` file (i.e. search for missing `.meta` files), and verifies +that that for each `.meta` file, a corresponding asset exists (i.e. search for dangling +`.meta` files). Each file will be reported as a separate test, which allows for easy +inspection in case of any failures. + +## Motivation - Ensuring committed metafiles are correct + +`.meta` files are an integral part of Unity's asset handling. The guids defined in these +files are used to define the links between different components. If a bad commit omits +a `.meta` file, a new one might be generated by each of the developers building on top +of this commit. This can further cascade in a huge problem which would be non trivial +to fix. This script aims to reduce these kind of problems by providing a static analysis +which would indicate if such a problem has occurred. When integrated with Pull Requests, +this will allow both the developer and the reviewer to quickly identify problematic +`.meta` files, and address the issue accordingly. + +For more information see for example ["Forgotten a .meta file? Stop the line!"](https://unityatscale.com/unity-meta-file-guide/forgotten-meta-file-stop-the-line/) +or similar article on the internet. + +## Configuration on TeamCity + +Using this script is rather trivial, and requires just a single build step. Due to the +nature of the TeamCity environment I am used to working, I prefer to use a "Command Line" +step running inside a python:3.10 docker container. + +The build step has the following 'Custom script:': + +```bash +python ./verify_metafiles.py "./Assets" # Assuming the cwd is in the Unity project folder. +``` + +Note that you can exclude specific folders and files with the `--exclude_dir` and `--exclude_file` +parameters. + +Additionally, I have configured the "Commit status publisher" and "Docker Support", to +ensure the Docker support is available and the results are published to GitHub. + +Alternative to the "Command Line" build step, the "Python" build step could be used as well. +The script itself has no dependencies and can be used as is.