Unity meta files check

Unity meta checker

A tool to check problems about meta files of Unity on Git 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

$ # 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):

$ 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 for more information.

Installation

Using Docker Image

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

$ 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 [<options>] [<path>]
...

Using GitHub Actions

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

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

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

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 }}"

Using Git Submodules

You can add unity-meta-check-bins as submodule into your git repository. This way is useful to ensure to use the same unity-meta-check version on CI or manual execution.

$ cd /path/to/your/repo
$ git submodule add [email protected]:dena/unity-meta-check-bins ./path/to/unity-meta-check-bins

$ ./path/to/unity-meta-check-bins/unity-meta-check-easy -help

Download binaries

Binaries are available on 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 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.

$ unity-meta-check -help
usage: unity-meta-check [<options>] [<path>]

Check missing or dangling .meta files.

  <path>
        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 <options> | unity-meta-check-junit path/to/junit.xml
  $ unity-meta-check <options> | unity-meta-check-github-pr-comment <options>
  $ unity-meta-check <options> | unity-meta-check-junit path/to/junit.xml | unity-meta-check-github-pr-comment <options>

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

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

guid: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TextScriptImporter:
  externalObjects: {}
  userData: 
  assetBundleName: 
  assetBundleVariant:

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

$ unity-meta-autofix -help
usage: unity-meta-autofix [<options>] <pattern> [<pattern>...]

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

ARGUMENTS
  <pattern>
        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 <options> | unity-meta-autofix -dry-run path/to/autofix
  $ unity-meta-check <options> | unity-meta-autofix <options> | <other-unity-meta-check-tool>

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.

$ unity-meta-check-junit -help
usage: unity-meta-check-junit [<options>] [<path>]

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

  <path>
        output path to write JUnit report

OPTIONS
  -version
        print version

EXAMPLE USAGES
  $ unity-meta-check <options> | unity-meta-check-junit path/to/junit-report.xml
  $ unity-meta-check <options> | unity-meta-check-junit path/to/junit-report.xml | <other-unity-meta-check-tool>

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.

$ unity-meta-check-github-pr-comment -help
usage: unity-meta-check-github-pr-comment [<options>]

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 <options> | 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 <options> | 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 <options> | unity-meta-check-junit path/to/unity-meta-check-result.xml | unity-meta-check-github-pr-comment <options> | <other-unity-meta-check-tool>

  $ export GITHUB_TOKEN="********"  # This should be set via credentials().
  $ unity-meta-check <options> | 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` |

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Unity meta files check

Tags

Unity meta checker

Basic Usage

Installation

Using Docker Image

Using GitHub Actions

Using Git Submodules

Download binaries

Advanced Usage

unity-meta-check

unity-meta-autofix

unity-meta-check-junit

unity-meta-check-github-pr-comment

Contributors (7)

Resources

About

Tags

Contributors (7)

Resources

Unity meta checker

Basic Usage

Installation

Using Docker Image

Using GitHub Actions

Using Git Submodules

Download binaries

Advanced Usage

unity-meta-check

unity-meta-autofix

unity-meta-check-junit

unity-meta-check-github-pr-comment

Contributors7 (7)

Resources

About

Tags

Contributors7 (7)

Resources

Contributors (7)

Contributors (7)