Skip to content

A tool to check problems about meta files of Unity

License

Notifications You must be signed in to change notification settings

DeNA/unity-meta-check

This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Mar 28, 2023
34cd22f · Mar 28, 2023
Jun 25, 2021
Jul 3, 2022
Apr 21, 2022
Feb 16, 2021
Mar 12, 2021
Mar 28, 2023
Feb 16, 2021
Jun 25, 2021
Feb 16, 2021
Jun 25, 2021
Jun 9, 2022
Jun 25, 2021
Feb 16, 2021
Mar 28, 2023
Mar 27, 2023
Jul 6, 2021
Mar 28, 2023
Jun 25, 2021
Feb 16, 2021
Jun 25, 2021
Jun 25, 2021
Jun 14, 2022
Jun 25, 2021
Feb 16, 2021
Jun 25, 2021
Jun 11, 2022
Mar 28, 2023
Jun 25, 2021
Jun 25, 2021
Jun 25, 2021
Feb 16, 2021

Repository files navigation

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 git@github.com: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` |