コンテンツにスキップ
Biome
Docs Blog Playground

Git Hooks

Gitでは、Git Hooks を使うことでgitコマンドの実行中にスクリプトを実行することができます。 例えば、コミットやプッシュの前にステージングされたファイルに対してformatやlintを実行できます。 Git Hooks の管理を簡単にするツールがいくつかあります。 以下のセクションでは、それらのツールで Biome を使う方法を紹介します。

Lefthook

Section titled Lefthook

Lefthookは高速で依存性のない、クロスプラットフォーム対応のフックマネージャです。 NPM経由でインストールできます。

Gitリポジトリのルートにlefthook.ymlというファイルを追加します。 以下は Lefthook の設定例です：

  • コミット前にformatとlintのチェックを行う

    lefthook.yml
    pre-commit:
      commands:
        check:
          glob: "*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}"
          run: npx biome check --no-errors-on-unmatched --files-ignore-unknown=true {staged_files}

  • コミット前にformatチェックやlintを行い、安全な修正を行う

    lefthook.yml
    pre-commit:
      commands:
        check:
          glob: "*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}"
          run: npx biome check --apply --no-errors-on-unmatched --files-ignore-unknown=true {staged_files} && git update-index --again

git update-index --again は、ステージングされたファイルを再度ステージングします。

  • プッシュ前にformatとlintのチェックを行う

    lefthook.yml
    pre-push:
      commands:
        check:
          glob: "*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}"
          run: npx biome check --no-errors-on-unmatched --files-ignore-unknown=true {pushed_files}

globと--files-ignore-unknown=true を併用する必要はありません。 --files-ignore-unknown=true を指定するだけで、Biomeが現在サポートしている（もしくは将来サポートするかもしれない）ファイルのみを対象にできます。 対象ファイルをさらにコントロールしたい場合は、glob を使ってください。

--no-errors-on-unmatchedは、どのファイルも処理されなかった場合に発生するエラーを抑制します。

設定後、lefthook install を実行してフックのセットアップを完了させましょう。

Husky

Section titled Husky

Huskyは、JavaScriptエコシステムで広く使われているフックマネージャーです。 Husky はステージングされていない変更を無視したり、ステージングされているファイルのみを対象としたりすることができません。 そのため、 lint-staged や git-format-staged といった別のツールと組み合わせて使われることが多いです。

プロジェクトに package.json が含まれている場合、scripts.prepare を使ってパッケージのインストール時に自動的に husky のフックを設定することができます：

package.json
{
  "scripts": {
    "prepare": "husky"
  }
}

lint-staged

Section titled lint-staged

lint-stagedは、JavaScriptのエコシステムで最も使われているツールのひとつです。

husky の設定に以下の項目を追加します：

.husky/pre-commit
lint-staged

lint-staged の設定は package.json に直接埋め込まれます。 Git Hooks を実行するときに便利なコマンドの例です：

package.json
{
  "lint-staged": {
    // Run Biome on staged files that have the following extensions: js, ts, jsx, tsx, json and jsonc
    // 次の拡張子を持つステージングファイルに対してBiomeを実行する: js, ts, jsx, tsx, json and jsonc
    "**.{js|ts|cjs|mjs|d.cts|d.mts|jsx|tsx|json|jsonc}": [
      "biome check --files-ignore-unknown=true", // フォーマットのチェックとリント
      "biome check --apply --no-errors-on-unmatched", // フォーマット、インポート文のソート、リント、安全な修正の適用
      "biome check --apply --organize-imports-enabled=false --no-errors-on-unmatched", // フォーマットと安全な修正の適用
      "biome check --apply-unsafe --no-errors-on-unmatched", // フォーマット、インポート文のソート、リント、安全及び安全ではない修正の適用
      "biome format --write --no-errors-on-unmatched", // フォーマット
      "biome lint --apply --no-errors-on-unmatched", // リントと安全な修正の適用
    ],
    // あるいは、すべてのファイルを渡し、不明な拡張子を無視することもできます
    "*": [
      "biome check --no-errors-on-unmatched --files-ignore-unknown=true", // フォーマットのチェックとリント
    ]
  }
}

処理されなかったファイルがない 場合を示すエラーを非表示にするため、コマンド実行時に--no-errors-on-unmatchedを使用することを忘れないでください。

git-format-staged

Section titled git-format-staged

lefthook、pre-commit、lint-staged などの他のツールとは対照的に、git-format-staged は内部的に git stash を使用しません。 これにより、ステージングされていない変更とステージングされた変更の間で衝突が発生した場合に、手動で介入する必要がなくなります。 詳しくは git-format-staged と他のツールの比較 を参照してください。

設定例：

  • コミット前にformatとlintのチェックを行う

    .husky/pre-commit
    git-format-staged --formatter 'biome check --files-ignore-unknown=true --no-errors-on-unmatched \"{}\"' .

  • コミット前にformatやlintのチェック・安全な修正を行う

    .husky/pre-commit
    git-format-staged --formatter 'biome check --apply --files-ignore-unknown=true --no-errors-on-unmatched \"{}\"' .

pre-commit

Section titled pre-commit

pre-commitは、多言語フックマネージャーです。 Biome は biomejs/pre-commit リポジトリ経由で4つの pre-commit のフックを提供します。

hook iddescription
biome-ciformatのチェック、インポート文が正しく並んでいるかのチェック、lint
biome-checkformat、インポート文の整理、lint、コミットされたファイルへ安全な修正の適用
biome-formatコミットされたファイルのformat
biome-lintlint、コミットされたファイルへ安全な修正の適用

以下の例では、リポジトリに pre-commit をインストールして pre-commit install を実行したと仮定します。 biome-check フックを使いたい場合は、プロジェクトのルートにある .pre-commit-config.yaml というファイルに次の設定を追加してください：

.pre-commit-config.yaml
repos:
-   repo: https://github.com/biomejs/pre-commit
    rev: "v0.1.0"  # タグやハッシュ値を指定してください
    hooks:
    -   id: biome-check
        additional_dependencies: ["@biomejs/biome@1.4.1"]

これでgit commitを実行したときに biome check --apply が実行されるようになりました。

pre-commitは別々にツールをインストールするため、pre-commit はどのツールがインストールされるか知っておく必要があります。 そのため、additional_dependencies オプションを使ってBiomeのバージョンを指定しなくてはいけません。

Biome がすでに npm のパッケージとしてローカルリポジトリにインストールされている場合、Biome を更新する際に package.json と .pre-commit-config.yaml の両方を更新するのは開発者の負担になります。 提供されているBiomeフックを使う代わりに、独自のローカルフックを指定できます。

例えば、npm を使用する場合、.pre-commit-config.yaml に以下のようなフックを書くことができます：

.pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: local-biome-check
        name: biome check
        entry: npx biome check --apply --files-ignore-unknown=true --no-errors-on-unmatched
        language: system
        types: [text]
        files: "\\.(jsx?|tsx?|c(js|ts)|m(js|ts)|d\\.(ts|cts|mts)|jsonc?)$"

Biome は--files-ignore-unknown=trueを指定することで未知のファイルを無視するため、pre-commit の files オプションは必須ではありません。

Shell script

Section titled Shell script

独自のシェルスクリプトを使うこともできます。 クロスプラットフォームの互換性に関する問題に遭遇する可能性があることに注意してください。 前のセクションで紹介したような専用ツールの使用をおすすめします。

シェルスクリプトの例：

  • コミット前にformatとlintのチェックを行う

    .git/hooks/pre-commit
    #!/bin/sh
    set -eu
    

    npx biome check --staged --files-ignore-unknown=true --no-errors-on-unmatched

  • コミット前にformatやlintのチェック、安全な修正を行う

    .git/hooks/pre-commit
    #!/bin/sh
    set -eu
    

    if ! git status --short | grep --quiet '^MM'; then
      printf '%s\n' "ERROR: Some staged files have unstaged changes" >&2
      exit 1;
    fi
    

    npx biome check --apply --staged --files-ignore-unknown=true --no-errors-on-unmatched
    

    git update-index --again

すでにステージングされたファイルに新たな変更がある場合は、フックを失敗させていることに注意してください。