Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/dena/unity-meta-check

A tool to check problems about meta files of Unity
https://github.com/dena/unity-meta-check

autofix ci testing tool unity

Last synced: 10 months ago
JSON representation

A tool to check problems about meta files of Unity

Awesome Lists containing this project

README 

          
Unity meta checker

=====================================



A tool to check problems about [meta files](https://docs.unity3d.com/2021.1/Documentation/Manual/AssetWorkflow.html) of [Unity](https://unity.com/) on [Git](https://git-scm.com/) repositories, and also the tool can do limited autofix for meta files of auto-generated files.



This tool can check the following problems:





Missing meta files




Missing means that an asset should have a meta file but the meta file is not committed. This problem can cause broken asset references.



Dangling meta files




Dangling means that a meta file exist, but the asset is not committed. This problem can cause annoying warning messages.






Basic Usage

-----------



```console

$ # Change the current directory to your Unity project or UPM package.

$ cd /path/to/unity/project



$ # Execute unity-meta-check (specifying -silent make that unity-meta-check only show results or fatal errors).

$ unity-meta-check -silent

missing: Assets/Not/Added.meta

missing: Packages/com.my.pkg/README.meta

missing: LocalPackages/com.local.pkg/README.meta

...

dangling: Assets/Not/Removed.meta

dangling: Packages/com.my.pkg/MyPkg.csproj.meta

dangling: LocalPackages/com.local.pkg/LocalPkg.csproj.meta

...



$ # unity-meta-check exit with non-zero status if one or more missing/dangling .meta files exist.

$ echo $?

1

```



Typically, unity-meta-check don't need to specify the target type (Unity project or UPM package) because unity-meta-check can automatically detect it.

You can explicitly specify `-unity-project` or `-upm-package` to disable the automatic detection, if the detection result was not intended.



If you want to ignore some problems, you can use `.meta-check-ignore` (this format is very similar to `.gitignore` but `!` is not supported):



```console

$ unity-meta-check -silent

missing: Assets/Not/Added1.meta

missing: Assets/NotAdded2.meta



$ # You can ignore these problems using .meta-check-ignore:

$ cat .meta-check-ignore

Assets/Not             # All files in the directory or the sub directories get ignored.

Assets/NotAdded2.meta  # Also can specify the path to files.



$ # unity-meta-check will ignore these problems.

$ unity-meta-check -silent

```



See [more advanced usage](#Advanced-Usage) for more information.



Installation

------------

### Using Docker Image



This way is recommended to use unity-meta-check on CI.



```console

$ docker pull ghcr.io/dena/unity-meta-check/unity-meta-check:latest



$ cd path/to/your/proj 

$ docker run -v "$(pwd):/target" --rm ghcr.io/dena/unity-meta-check/unity-meta-check:latest -silent /target

missing Assets/AssetsMissing.meta

missing LocalPackages/com.example.local.pkg/LocalPkgMissing.meta

missing Packages/com.example.pkg/PkgMissing.meta

dangling Assets/AssetsDangling.meta

dangling LocalPackages/com.example.local.pkg/LocalPkgDangling.meta

dangling Packages/com.example.pkg/PkgDangling.meta



$ docker run --rm ghcr.io/dena/unity-meta-check/unity-meta-check:latest -help

usage: unity-meta-check [] []

...

```



### Using GitHub Actions



To check only, the following YAML can cover almost case:



```yaml

name: Meta Check

on: pull_request



jobs:

  meta-check:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v2

      - uses: DeNA/unity-meta-check@v3

```



See [`./action.yml`](./action.yml) for more detials.



Advanced Usage for JUnit report + Autofix + PR Comment report



The following YAML is the example for JUnit report + Autofix + PR Comment report:



```yaml

name: Meta Check

on: pull_request



jobs:

  unity-meta-check:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v2

      - uses: DeNA/unity-meta-check@v3

        with:

          enable_autofix: true

          autofix_globs: .

          enable_junit: true

          junit_xml_path: junit.xml

          enable_pr_comment: true

          pr_comment_lang: ja

          pr_comment_send_success: true

        env:

          GITHUB_TOKEN: "${{ secrets.YOUR_GITHUB_TOKEN }}"



      - name: See how autofix did

        run: git status

        if: always()



      - uses: mikepenz/action-junit-report@v2

        with:

          report_paths: junit.xml

        if: always()

```



Advanced Usage for push events instead of pull_request events



```yaml

name: Meta Check

on: push



jobs:

  meta-check:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v2



      - uses: jwalton/gh-find-current-pr@v1

        id: findPr



      - uses: DeNA/unity-meta-check@v3

          enable_pr_comment: true

          pr_comment_pull_number: ${{ steps.findPr.outputs.number }}

        env:

          GITHUB_TOKEN: "${{ secrets.YOUR_GITHUB_TOKEN }}"

```



### Download binaries



Binaries are available on [releases](https://github.com/dena/unity-meta-check/releases).



Advanced Usage

--------------



Provided features are built on several individual binaries:







unity-meta-check



Checker for missing/dangling meta files. The result print to stdout.





unity-meta-check-autofix



Autofix for meta files problems. It need a result of unity-meta-check via stdin.





unity-meta-check-junit



Reporter for Jenkins compatible XML based JUnit reports. It need a result of unity-meta-check from stdin.





unity-meta-check-github-pr-comment



Reporter for GitHub comments of GitHub issues or pull requests. It need a result of unity-meta-check from stdin.






### unity-meta-check



`unity-meta-check` checks missing/dangling meta files on the commit.



This check based on [a git tree object](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects#_tree_objects) instead of the working directory. It means you **MUST** commit adding missing meta files or removing dangling meta files to re-check by `unity-meta-check`.



Other complemental features such as autofix or reporting are provided other binaries.



```console

$ unity-meta-check -help

usage: unity-meta-check [] []



Check missing or dangling .meta files.



  

        root directory of your Unity project or UPM package to check (default "$(git rev-parse --show-toplevel)")



OPTIONS

  -debug

        set log level to DEBUG (default INFO)

  -ignore-file string

        path to .meta-check-ignore

  -ignore-dangling

        ignore dangling .meta

  -ignore-submodules

        ignore git submodules and nesting repositories (this is RECOMMENDED but not enabled by default because it can cause to miss problems in submodules or nesting repositories)

  -no-ignore-case

        treat case of file paths

  -silent

        set log level to WARN (default INFO)

  -unity-project

        check as Unity project

  -unity-project-sub-dir

        check as sub directory of Unity project

  -upm-package

        check as UPM package (same meaning of -unity-project-sub-dir)

  -version

        print version



EXAMPLE USAGES

  $ cd path/to/UnityProject

  $ unity-meta-check -silent



  $ cd path/to/any/dir

  $ unity-meta-check -silent -upm-package path/to/MyUPMPackage

  $ unity-meta-check -silent -unity-project-sub-dir path/to/UnityProject/Assets/Sub/Dir



EXAMPLE USAGES WITH OTHER TOOLS

  $ unity-meta-check  | unity-meta-check-junit path/to/junit.xml

  $ unity-meta-check  | unity-meta-check-github-pr-comment 

  $ unity-meta-check  | unity-meta-check-junit path/to/junit.xml | unity-meta-check-github-pr-comment 

```



If both `-silent` and `-debug` are specified, `-silent` win.



### unity-meta-autofix



`unity-meta-autofix` fix (very limited) problems about meta files. It needs a result of `unity-meta-check` via stdin. It can fix the following problems:





Missing meta files for folders






Example of auto-generated meta files



```yaml

fileFormatVersion: 2

guid: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

folderAsset: yes

DefaultImporter:

  externalObjects: {}

  userData: 

  assetBundleName: 

  assetBundleVariant: 

```



Automatic GUID generation does not depend on time, so it is safe if autofix runs parallel.





Missing meta files for some binaries



Sometimes you need to import auto-generated binary data files (like encoded as Protocol Buffer Binary Wire Format) programmatically. Then, autofix feature is useful because it can add meta files to the binaries.



Example of auto-generated meta files



```yaml

guid: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

TextScriptImporter:

  externalObjects: {}

  userData: 

  assetBundleName: 

  assetBundleVariant: 

```



Automatic GUID generation does not depend on time, so it is safe if autofix runs parallel.








```console

$ unity-meta-autofix -help

usage: unity-meta-autofix []  [...]



Fix missing or dangling .meta. Currently autofix is only limited support.



ARGUMENTS

  

        glob pattern to path where autofix allowed on



OPTIONS

  -debug

        set log level to DEBUG (default INFO)

  -dry-run

        dry run

  -root-dir string

        directory path to where unity-meta-check checked at (default ".")

  -silent

        set log level to WARN (default INFO)

  -version

        print version



EXAMPLE USAGES

  $ unity-meta-check  | unity-meta-autofix -dry-run path/to/autofix

  $ unity-meta-check  | unity-meta-autofix  | 

```



Currently, autofix for dangling meta files is not supported, because it might be dangerous on some situations.



### unity-meta-check-junit



`unity-meta-check-junit` is a reporter for Jenkins compatible XML based JUnit reports. It needs a result of `unity-meta-check` via stdin.



```console

$ unity-meta-check-junit -help

usage: unity-meta-check-junit [] []



Save a JUnit report file for the result from unity-meta-check via STDIN.



  

        output path to write JUnit report



OPTIONS

  -version

        print version



EXAMPLE USAGES

  $ unity-meta-check  | unity-meta-check-junit path/to/junit-report.xml

  $ unity-meta-check  | unity-meta-check-junit path/to/junit-report.xml | 

```



### unity-meta-check-github-pr-comment



`unity-meta-check-github-pr-comment` is a reporter for GitHub comments of GitHub issues or pull requests. It needs a result of `unity-meta-check` via stdin.



![](./docs/images/unity-meta-check-github-pr-comment-screenshot.png)



```console

$ unity-meta-check-github-pr-comment -help

usage: unity-meta-check-github-pr-comment []



Post a comment for the result from unity-meta-check via STDIN to GitHub Pull Request.



OPTIONS

  -api-endpoint string

        GitHub API endpoint URL (like https://github.example.com/api/v3) (default "https://api.github.com")

  -debug

        set log level to DEBUG (default INFO)

  -lang string

        language code (available: en, ja) (default "en")

  -owner string

        owner of the GitHub repository

  -pull uint

        pull request number

  -repo string

        name of the GitHub repository

  -silent

        set log level to WARN (default INFO)

  -template-file string

        custom template file

  -version

        print version



ENVIRONMENT

  GITHUB_TOKEN

        GitHub API token. The scope can be empty if your repository is public. Otherwise, the scope should contain "repo"



EXAMPLE USAGES

  $ export GITHUB_TOKEN="********"

  $ unity-meta-check  | unity-meta-check-github-pr-comment \

      -api-endpoint https://api.github.com \

      -owner example-org \

      -repo my-repo \

      -pull "$CIRCLE_PR_NUMBER"  # This is for CircleCI



  $ export GITHUB_TOKEN="********"  # This should be set via credentials().

  $ unity-meta-check  | unity-meta-check-github-pr-comment \

      -api-endpoint https://github.example.com/api/v3 \

      -owner example-org \

      -repo my-repo \

      -pull "$ghprbPullId"  # This is for Jenkins with GitHub PullRequest Builder plugin



  $ GITHUB_TOKEN="********" unity-meta-check  | unity-meta-check-junit path/to/unity-meta-check-result.xml | unity-meta-check-github-pr-comment  | 



  $ export GITHUB_TOKEN="********"  # This should be set via credentials().

  $ unity-meta-check  | unity-meta-check-github-pr-comment \

      -api-endpoint https://github.example.com/api/v3 \

      -owner example-org \

      -repo my-repo \

      -pull "$ghprbPullId" \

      -template-file path/to/template.json  # template file can be used for localization for GitHub comments.



TEMPLATE FILE FORMAT EXAMPLE

  If a template file is like:



  {

    "success": "No missing/dangling .meta found. Perfect!",

    "failure": "Some missing or dangling .meta found. Fix commits are needed.",

    "header_status": "Status",

    "header_file_path": "File",

    "status_missing": "Not committed",

    "status_dangling": "Not removed"

  }



  then the output become:



  No missing/dangling .meta found. Perfect!



  or:



  Some missing or dangling .meta found. Fix commits are needed.



  | Status | File |

  |:--|:--|

  | Not committed | `path/to/missing.meta` |

  | Not removed | `path/to/dangling.meta` |

```