Lefthook

Lefthook リファレンス

Lefthook（lefthook.dev）の全ドキュメントを網羅したスキル。 ユーザーのタスクに応じて適切な README.md を読み、そこから個別ファイルへ辿ること。

ディレクトリ構成

skills/lefthook/
  SKILL.md
  references/
    installation/
      README.md
      overview.md
      node.md
      ruby.md
      go.md
      python.md
      swift.md
      homebrew.md
      winget.md
      scoop.md
      deb.md
      rpm.md
      alpine.md
      arch.md
      snap.md
      devbox.md
      mise.md
      manual.md
    configuration/
      README.md
      global-settings.md
      hook-settings.md
      command-settings.md
      script-settings.md
      source-dir.md
      remotes.md
    usage/
      README.md
      commands.md
      environment-variables.md
    examples/
      README.md
      commitlint.md
      filters.md
      lefthook-local.md
      remotes.md
      skip.md
      stage-fixed.md
      wrap-commands.md
  samples/
    README.md
    basic-setup.md
    parallel-execution.md
    auto-fix-and-stage.md
    commitlint-integration.md
    local-override.md
    conditional-skip.md
    monorepo-setup.md
    shared-config-via-remotes.md
  scripts/
    README.md
    cli.md
    install.md
    run-with-env.md

探索手順

タスクからカテゴリを引き、カテゴリの README.md で目的のページを特定する:

1. 下記マッピング表でタスクに対応するカテゴリを探す 2. そのカテゴリの references/{category}/README.md を参照して目的のページを特定する 3. 該当ページの .md を Read して詳細を確認する

タスク → カテゴリ マッピング

Command Settings

Source: https://lefthook.dev/configuration

フックで実行されるコマンドの設定。各コマンドには名前と関連する run オプションがある。

Commands

Source: https://lefthook.dev/configuration/Commands

# lefthook.yml

pre-commit:
  commands:
    lint:
      run: yarn lint
      glob: "*.js"

利用可能なコマンドオプション

• run - コマンド実行文字列
• skip / only - 条件付き実行制御
• tags - カテゴリ分けタグ
• glob - ファイルパターンマッチング
• files - ファイル指定コマンド
• file_types - ファイルタイプフィルタリング
• env - 環境変数
• root - 作業ディレクトリ
• exclude - 除外パターン
• fail_text - カスタム失敗メッセージ
• stage_fixed - 修正ファイルの自動ステージング
• interactive - 対話モード
• use_stdin - 標準入力処理
• priority - 実行優先順位

---

name

Source: https://lefthook.dev/configuration/name

• 型: String

ジョブにラベルを付与し、サマリー出力に表示する。同じ名前のジョブはローカル設定や extends 設定からマージされる。

# lefthook.yml

pre-commit:
  jobs:
    - name: lint and fix
      run: yarn run eslint --fix {staged_files}

---

run

Source: https://lefthook.dev/configuration/run

• 型: String (必須)

sh シェルを使用して実行する実際のコマンドを指定する。

利用可能なテンプレート

• {files} - files コマンドの結果
• {staged_files} - コミット用にステージされたファイル
• {push_files} - コミット済み未プッシュのファイル
• {all_files} - git 追跡のすべてのファイル
• {cmd} - lefthook.yml のコマンドの省略形
• {0} - すべての git フック引数のスペース結合文字列
• {1}, {2}, {3} - 個別の git フック引数（番号付き）
• {lefthook_job_name} - 現在のジョブ/コマンド/スクリプト名

コマンドラインの長さにはシステムごとに制限がある。ファイルリストが長い場合、lefthook はファイルリストを分割して複数のコマンドを順次実行する。

基本コマンド

pre-commit:
  commands:
    lint:
      run: yarn lint

ステージファイルの使用

pre-commit:
  commands:
    eslint:
      glob: "*.{js,ts,jsx,tsx}"
      run: yarn eslint {staged_files}

ファイルフィルタリング

pre-commit:
  commands:
    govet:
      files: git ls-files -m
      glob: "*.go"
      run: go vet -- {files}

Git 引数の使用

commit-msg:
  commands:
    multiple-sign-off:
      run: 'test $(grep -c "^Signed-off-by: " {1}) -lt 2'

クォート付きファイル

pre-commit:
  commands:
    lint:
      glob: "*.js"
      run: yarn eslint "{staged_files}"

マルチラインスクリプト

pre-commit:
  jobs:
    - name: a whole script in a run
      run: |
        for file in $(ls .); do
          yarn lint $file
        done

---

args

Source: https://lefthook.dev/configuration/args

• 型: String
• 追加バージョン: lefthook 2.0.5

スクリプトに引数を渡す、または lefthook-local.yml でコマンドの引数を上書きする。run オプションと同じテンプレート変数をサポートする。

注意: args を指定すると Git が渡す引数は省略される。args を省略するか args: "{0}" を設定すると同じ結果になる。

# lefthook.yml

pre-commit:
  jobs:
    - script: check-python-files.sh
      runner: bash
      args: "{staged_files}"
      glob: "*.py"

    - run: yarn lint
      args: "{staged_files}"
      glob:
        - "*.ts"
        - "*.js"

---

group

Source: https://lefthook.dev/configuration/group

複数のジョブをまとめて、ユニットとしての実行方法を定義する。

サブオプション

• parallel: グループ内のすべてのジョブを同時実行
• piped: ジョブを順次実行
• jobs: グループに含まれるジョブ

継承プロパティ

env、root、glob、exclude がグループに定義されると、ジョブレベルで上書きされない限り、すべての配下ジョブに伝播する。

並列実行グループ

pre-commit:
  jobs:
    - group:
        parallel: true
        jobs:
          - run: echo 1
          - run: echo 2
          - run: echo 3

継承設定付きグループ

pre-commit:
  jobs:
    - env:
        E1: hello
      glob:
        - "*.md"
      exclude:
        - "README.md"
      root: "subdir/"
      group:
        parallel: true
        jobs:
          - run: echo $E1
          - run: echo $E1
            env:
              E1: bonjour

マージ用名前付きグループ

pre-commit:
  jobs:
    - name: a name of a group
      group:
        jobs:
          - name: lint
            run: yarn lint
          - name: test
            run: yarn test

グループのマージを有効にするには、個々のジョブだけでなくグループジョブ自体に name を割り当てること。

---

tags

Source: https://lefthook.dev/configuration/tags

• 型: Array of strings

コマンドとスクリプトにタグを指定する。exclude_tags による選択的除外に有用。

# lefthook.yml

pre-commit:
  commands:
    lint:
      tags:
        - frontend
        - js
      run: yarn lint
    test:
      tags:
        - backend
        - ruby
      run: bundle exec rspec

---

glob

Source: https://lefthook.dev/configuration/glob

• 型: String / Array of strings

コマンドのファイルをフィルタリングする。run オプションでファイルテンプレートを使用するか、カスタム files コマンドを提供する場合にのみ適用される。

単一 glob パターン

pre-commit:
  jobs:
    - name: lint
      run: yarn eslint {staged_files}
      glob: "*.{js,ts,jsx,tsx}"

複数 glob パターン（v1.10.10+）

pre-commit:
  jobs:
    - run: yarn lint {staged_files}
      glob:
        - "*.ts"
        - "*.js"

ファイルテンプレートなしでの使用

pre-commit:
  jobs:
    - name: lint
      run: npm run lint
      glob: "*.js"

- glob は実際の git リポジトリルートから計算される（root 設定は無視）

- デフォルトでは ** は 1 つ以上のディレクトリにマッチ。ルートレベルも含めるには glob_matcher: doublestar を使用

- run にファイルテンプレートなしで glob を指定すると、pre-commit では {staged_files}、pre-push では {push_files} を自動チェック

---

files

Source: https://lefthook.dev/configuration/files

• 型: String (シェルコマンド)

{files} テンプレートで参照されるファイルまたはディレクトリを返すカスタムコマンド。ジョブレベルの files はフックレベルの files を上書きする。出力が空の場合、ジョブの実行はスキップされる。

# lefthook.yml

pre-push:
  commands:
    stylelint:
      tags:
        - frontend
        - style
      files: git diff --name-only master
      glob: "*.js"
      run: yarn stylelint {files}

# lefthook.yml

pre-push:
  commands:
    rubocop:
      tags: backend
      glob: "**/*.rb"
      files: node ./lefthook-scripts/ls-files.js
      run: bundle exec rubocop --force-exclusion --parallel -- {files}

---

file_types

Source: https://lefthook.dev/configuration/file_types

• 型: String / Array of strings

run テンプレート内のファイルをファイルタイプでフィルタリングする。

サポートされるファイルタイプ

ロジックルール

• AND ロジック: text, binary, executable, not executable, symlink, not symlink
• OR ロジック: MIME タイプ

pre-commit:
  commands:
    lint-code:
      run: yarn lint {staged_files}
      file_types: text
    check-hex-codes:
      run: yarn check-hex {staged_files}
      file_types: binary

pre-commit:
  jobs:
    - run: typos -w -- {staged_files}
      file_types:
        - text/x-perl
        - text/x-python
        - text/x-php
        - text/x-lua
        - text/x-sh

---

env

Source: https://lefthook.dev/configuration/env

• 型: Object (キーと値のペア)

コマンドまたはスクリプトの環境変数を指定する。

# lefthook.yml

pre-commit:
  commands:
    test:
      env:
        RAILS_ENV: test
      run: bundle exec rspec

PATH の拡張

GUI アプリケーション経由で lefthook を実行する場合、シェル設定の PATH 変更が利用できないことがある。

# lefthook-local.yml

pre-commit:
  commands:
    test:
      env:
        PATH: $PATH:/home/me/path/to/yarn

---

root

Source: https://lefthook.dev/configuration/root

• 型: String (ディレクトリパス)

コマンド実行の現在の作業ディレクトリ（CWD）を変更する。npm や yarn など、設定ファイルがリポジトリルートと異なるディレクトリにある場合に有用。

pre-push、pre-commit フック、カスタム files コマンドでは、root オプションはファイルパスをフィルタリングする。

# lefthook.yml

pre-commit:
  commands:
    lint:
      root: "client/"
      glob: "*.{js,ts}"
      run: yarn eslint --fix {staged_files} && git add {staged_files}

重要: glob はリポジトリのルートから計算される。root ディレクトリからではない。

---

fail_text

Source: https://lefthook.dev/configuration/fail_text

• 型: String

コマンドまたはスクリプトが失敗した際に表示するカスタムエラーメッセージ。

# lefthook.yml

pre-commit:
  commands:
    lint:
      run: yarn lint
      fail_text: Add node executable to $PATH

出力例:

$ git commit -m 'fix: Some bug'

Lefthook v1.1.3
RUNNING HOOK: pre-commit

  EXECUTE > lint

SUMMARY: (done in 0.01 seconds)
  lint: Add node executable to $PATH env

---

stage_fixed

Source: https://lefthook.dev/configuration/stage_fixed

• 型: Boolean
• デフォルト: false
• スコープ: pre-commit フック専用

コマンドまたはスクリプトの実行後にファイルを自動的に git add でステージする。

• files オプションが指定されたコマンドの場合、そのコマンドがステージング対象ファイルを取得
• files オプションなしのスクリプトとコマンドでは、{staged_files} テンプレートが対象ファイルを決定
• glob と exclude のフィルタが適用される

# lefthook.yml

pre-commit:
  commands:
    lint:
      run: npm run lint --fix {staged_files}
      stage_fixed: true

---

interactive

Source: https://lefthook.dev/configuration/interactive

• 型: Boolean
• デフォルト: false

コマンドまたはスクリプトを対話モードで実行し、CLI からの入力を受け付ける。

• すべての interactive コマンド/スクリプトは非対話のものの後に実行される（piped 有効時を除く）
• Lefthook は /dev/tty を開いて stdin として使用する
• no_tty オプションが設定されている場合、interactive は無視される

CLI からの入力なしで stdin をコマンドに渡す必要がある場合は use_stdin を使用すること。

# lefthook.yml

pre-commit:
  commands:
    format:
      interactive: true
      run: yarn format --interactive

---

use_stdin

Source: https://lefthook.dev/configuration/use_stdin

• 型: Boolean
• デフォルト: false

OS からの stdin をコマンド/スクリプトに渡す。pre-push フックなど、stdin からデータを行ごとに読み取るフックに有用。

複数のコマンド/スクリプトで use_stdin: true を設定した場合、入力データを受け取るのは 1 つだけで、他は何も受け取らない。

pre-push:
  scripts:
    "do-the-magic.sh":
      runner: bash
      use_stdin: true

# .lefthook/pre-push/do-the-magic.sh

remote="$1"
url="$2"

while read local_ref local_oid remote_ref remote_oid; do
  # ...
done

---

priority

Source: https://lefthook.dev/configuration/priority

• 型: Number
• デフォルト: 0

順次ステップの実行順序を制御する。parallel: false または piped: true が設定されている場合にのみ有効。

値 0 は +Infinity として扱われ、priority: 0 またはこの設定なしのコマンド/スクリプトは最後に実行される。

# lefthook.yml

post-checkout:
  piped: true
  commands:
    db-create:
      priority: 1
      run: rails db:create
    db-migrate:
      priority: 2
      run: rails db:migrate
    db-seed:
      priority: 3
      run: rails db:seed

  scripts:
    "check-spelling.sh":
      runner: bash
      priority: 1
    "check-grammar.rb":
      runner: ruby
      priority: 2

Global Settings

Source: https://lefthook.dev/configuration

Lefthook のグローバル設定オプション。プロジェクト全体の動作を制御する設定項目をまとめている。

Config File Names

Lefthook は複数の設定ファイル形式と命名規則をサポートする。

YAML Format

• lefthook.yml / lefthook.yaml
• .lefthook.yml / .lefthook.yaml
• .config/lefthook.yml / .config/lefthook.yaml

TOML Format

• lefthook.toml / .lefthook.toml / .config/lefthook.toml

JSON / JSONC Format

• lefthook.json / .lefthook.json / .config/lefthook.json
• lefthook.jsonc / .lefthook.jsonc / .config/lefthook.jsonc

プロジェクト内に複数の設定ファイルがある場合、どれが使われるか不定となるため、1つのフォーマットのみ使用すること。

Local Configuration

Lefthook は lefthook-local（任意のサポート形式）という追加設定ファイルを自動的にマージする。-local ファイルはメイン設定と同じ命名規則（ドット有無）に従う必要がある。-local ファイルは単独でも使用可能。

Merge Order

設定の優先順位（低 → 高）:

1. lefthook.yml - メイン設定ファイル 2. extends - extends オプションの設定 3. remotes - remotes オプションの設定 4. lefthook-local.yml - ローカル設定ファイル

---

assert_lefthook_installed

Source: https://lefthook.dev/configuration/assert_lefthook_installed

• 型: Boolean
• デフォルト: false

true に設定すると、lefthook 実行ファイルが見つからない場合にステータスコード 1 で終了する。$PATH、node_modules/、Ruby gem インストールなど複数の場所を検索する。

# lefthook.yml

assert_lefthook_installed: true

---

colors

Source: https://lefthook.dev/configuration/colors

• 型: Boolean / String (auto) / Object
• デフォルト: auto

Lefthook のカラー出力を有効/無効にする。--colors オプションで上書き可能。カスタムカラーコードも指定できる。

無効化

# lefthook.yml

colors: false

カスタムカラーコード

# lefthook.yml

colors:
  cyan: 14
  gray: 244
  green: '#32CD32'
  red: '#FF1493'
  yellow: '#F0E68C'

環境変数

• NO_COLOR=true - Lefthook とすべてのサブコマンドでカラー出力を無効化
• CLICOLOR_FORCE=true - Lefthook とすべてのサブコマンドでカラー出力を強制

---

extends

Source: https://lefthook.dev/configuration/extends

• 型: Array of strings (ファイルパス)

追加の YAML ファイルから設定をマージして拡張する。lefthook.yml、lefthook-local.yml、リモート設定それぞれで個別に使用可能。アスタリスクによる glob パターンをサポートする。

# lefthook.yml

extends:
  - /home/user/work/lefthook-extend.yml
  - /home/user/work/lefthook-extend-2.yml
  - lefthook-extends/file.yml
  - ../extend.yml
  - projects/*/specific-lefthook-config.yml

---

min_version

Source: https://lefthook.dev/configuration/min_version

• 型: String (セマンティックバージョニング)

lefthook バイナリの最小バージョン要件を指定する。設定で特定バージョン以降の機能を使用する場合に有用。

# lefthook.yml

min_version: 1.1.3

---

no_auto_install

Source: https://lefthook.dev/configuration/no_auto_install

• 型: Boolean
• デフォルト: false

デフォルトでは lefthook は設定変更を検知すると lefthook run 実行時にフックを自動インストール・更新する。true に設定するとこの自動動作を無効化する。--no-auto-install フラグでも制御可能。

# lefthook.yml

no_auto_install: true

pre-commit:
  commands:
    lint:
      run: npm run lint

---

no_tty

Source: https://lefthook.dev/configuration/no_tty

• 型: Boolean
• デフォルト: false

スピナーなどの対話的な視覚要素を非表示にする。CI/CD パイプラインなど非対話環境で有用。--no-tty フラグでも制御可能。

# lefthook.yml

no_tty: true

---

output

Source: https://lefthook.dev/configuration/output

• 型: Array of strings / Boolean
• デフォルト: すべて有効

Lefthook のコンソール出力の詳細度を管理する。

指定可能な値

• meta - lefthook バージョンを表示
• summary - サマリーブロック（成功・失敗のステップ）を表示
• empty_summary - 実行ステップがない場合にサマリー見出しを表示
• success - 成功したステップを表示
• failure - 失敗したステップを表示
• execution - 実行ログを表示
• execution_out - 実行出力を表示
• execution_info - EXECUTE > ... ログを表示
• skips - 「skip」メッセージ（ファイル不一致など）を表示

# lefthook.yml

output:
  - meta
  - summary
  - empty_summary
  - success
  - failure
  - execution
  - execution_out
  - execution_info
  - skips

環境変数による上書き

LEFTHOOK_OUTPUT="meta,success,summary" lefthook run pre-commit

エラー以外のすべての出力を無効にするには output: false を設定する。

---

rc

Source: https://lefthook.dev/configuration/rc

• 型: String (ファイルパス)

非シェルプログラムからアクセスできない環境変数を設定するシェルスクリプトファイルを指定する。GUI アプリケーション（VSCode など）から git フックを実行する場合や、rbenv/nvm 等でカスタマイズされた PATH に依存する場合に有用。

設定例

rc: ~/.lefthookrc

rc: '"${XDG_CONFIG_HOME:-$HOME/.config}/lefthookrc"'

RC ファイルの内容例

# nvm を使用する場合
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# fnm を使用する場合
export FNM_DIR="$HOME/.fnm"
[ -s "$FNM_DIR/fnm.sh" ] && \. "$FNM_DIR/fnm.sh"

# 直接 PATH を変更
PATH=$PATH:$HOME/.nvm/versions/node/v15.14.0/bin

注意: rc オプション設定後は git フックの再インストールが必要: lefthook install -f

---

skip_lfs

Source: https://lefthook.dev/configuration/skip_lfs

• 型: Boolean
• デフォルト: false

システムに LFS が存在しても LFS フックの実行をスキップする。

# lefthook.yml

skip_lfs: true

pre-push:
  commands:
    test:
      run: yarn test

---

glob_matcher

Source: https://lefthook.dev/configuration/glob_matcher

• 型: String (enum)
• デフォルト: gobwas
• 許可値: gobwas, doublestar

lefthook がファイルフィルタリングに使用する glob パターンマッチングエンジンを選択する。

動作の違い

gobwas（デフォルト）:

• **/*.js は folder/file.js、a/b/c/file.js にマッチ
• **/*.js はルートレベルの file.js にマッチしない

doublestar:

• **/*.js は file.js、folder/file.js、a/b/c/file.js にマッチ
• 標準的な glob 実装と一致

# lefthook.yml

glob_matcher: doublestar

pre-commit:
  jobs:
    - name: lint
      run: yarn eslint {staged_files}
      glob: "**/*.{js,ts}"

この設定はグローバルで、すべての glob と exclude パターンに適用される。

---

templates

Source: https://lefthook.dev/configuration/templates

• 型: Object (キーと値のペア)
• 追加バージョン: lefthook 1.10.8

run 値のテンプレートに対するカスタム置換を提供する。コマンドのラッパー（Docker、依存関係マネージャーなど）で冗長性を削減するのに有用。

# lefthook.yml
templates:
  dip:

pre-commit:
  jobs:
    - run: {dip} bundle exec rubocop -- {staged_files}

# lefthook-local.yml
templates:
  dip: dip

冗長性の削減

templates:
  wrapper: docker-compose run --rm -v $(pwd):/app service

pre-commit:
  jobs:
    - run: {wrapper} yarn format
    - run: {wrapper} yarn lint
    - run: {wrapper} yarn test

lefthook.yml で定義したテンプレートは lefthook-local.yml で上書き可能。

---

install_non_git_hooks

Source: https://lefthook.dev/configuration/install_non_git_hooks

• 型: Boolean
• 追加バージョン: lefthook 2.0.17

非 Git フックを .git/hooks にインストールする。git-flow などのツールとの統合に有用。

# lefthook.yml

install_non_git_hooks: true

---

lefthook

Source: https://lefthook.dev/configuration/lefthook

• 型: String

lefthook 実行ファイルへのフルパス、またはブーンシェル（sh）構文でのコマンドを指定する。特定バージョンの lefthook を依存関係から強制使用する場合や、PnP ローダーなどの特殊なプロジェクト構成に有用。

注意: このオプションはセキュリティ上の理由から remotes や extends からはマージされない。lefthook-local.yml からのマージは行われる。

実行ファイルパスの直接指定

lefthook: /usr/bin/lefthook

pre-commit:
  jobs:
    - run: yarn lint

ディレクトリ移動を伴うコマンド

lefthook: |
  cd project-with-lefthook
  pnpm lefthook

pre-commit:
  jobs:
    - run: yarn lint
      root: project-with-lefthook

パッケージマネージャーラッパー

lefthook: bundle exec lefthook

pre-commit:
  jobs:
    - run: bundle exec rubocop -- {staged_files}

デバッグ用環境変数の付与

# lefthook-local.yml
lefthook: LEFTHOOK_VERBOSE=1 lefthook

Hook Settings

Source: https://lefthook.dev/configuration

Git フック（commands、scripts、skip ルールなど）の設定を含む。任意の Git フックまたはカスタムフック（例: test）を指定できる。

Hook

Source: https://lefthook.dev/configuration/Hook

基本例

# lefthook.yml

# Git フック
pre-commit:
  jobs:
    - run: yarn lint {staged_files} --fix
      stage_fixed: true

# カスタムフック
check-docs:
  jobs:
    - run: yarn check-docs
    - run: typos

主要プロパティ

---

parallel

Source: https://lefthook.dev/configuration/parallel

• 型: Boolean
• デフォルト: false

デフォルトでは lefthook はコマンドとスクリプトを順次実行する。true に設定すると並列実行が有効になる。

# lefthook.yml

pre-commit:
  parallel: true
  commands:
    lint:
      run: yarn lint
    test:
      run: yarn test

---

piped

Source: https://lefthook.dev/configuration/piped

• 型: Boolean
• デフォルト: false

コマンドやスクリプトのいずれかが失敗した場合に実行を停止する。後続のステップが前のステップの成功に依存する順次操作に有用。

注意: piped: true と parallel: true の両方を設定するとエラーになる。これらは相互排他的。

# lefthook.yml

database:
  piped: true
  commands:
    1_create:
      run: rake db:create
    2_migrate:
      run: rake db:migrate
    3_seed:
      run: rake db:seed

---

follow

Source: https://lefthook.dev/configuration/follow

• 型: Boolean
• デフォルト: false

実行中のコマンドとスクリプトの STDOUT を追跡する。

# lefthook.yml

pre-push:
  follow: true
  commands:
    backend-tests:
      run: bundle exec rspec
    frontend-tests:
      run: yarn test

parallel オプションと併用すると出力フォーマットが不明確になる可能性があるため、両方の同時有効化は避けること。

---

files (Hook-Level)

Source: https://lefthook.dev/configuration/files-global

• 型: String (シェルコマンド)

{files} テンプレートで参照されるファイルまたはディレクトリのリストを返すカスタムシェルコマンドを定義する。sh シェルで実行される。コマンドが空の結果を返すと、関連コマンドの実行はスキップされる。

pre-commit:
  files: git diff --name-only master
  commands:
    lint:
      run: yarn lint {files}

---

fail_on_changes

Source: https://lefthook.dev/configuration/fail_on_changes

• 型: String
• デフォルト: never

フック実行中に git 追跡ファイルが変更された場合の lefthook の終了方法を制御する。

指定可能な値

• never: ファイルが変更されても非ゼロステータスで終了しない（デフォルト）
• always: ファイルが変更された場合に常に非ゼロステータスで終了
• ci: CI 環境変数が設定されている場合のみ失敗で終了。stage_fixed と併用してローカル開発をスムーズに、CI を厳格に
• non-ci: CI 環境変数がない場合のみ失敗で終了

# lefthook.yml

pre-commit:
  parallel: true
  fail_on_changes: "always"
  commands:
    lint:
      run: yarn lint
    test:
      run: yarn test

---

fail_on_changes_diff

Source: https://lefthook.dev/configuration/fail_on_changes_diff

• 型: Boolean
• デフォルト: CI 環境では自動的に diff を出力、それ以外では非表示

fail_on_changes オプションが発動した際に検出された変更の diff を出力するかどうかを制御する。

# lefthook.yml

pre-commit:
  parallel: true
  fail_on_changes: "always"
  fail_on_changes_diff: true
  commands:
    lint:
      run: yarn lint
    test:
      run: yarn test

• true: すべての環境で diff 出力を有効化
• false: CI パイプラインでも diff 出力を抑制

---

exclude_tags

Source: https://lefthook.dev/configuration/exclude_tags

• 型: Array of strings / String

除外したいタグまたはコマンド名。LEFTHOOK_EXCLUDE 環境変数で上書き可能。

# lefthook.yml

pre-commit:
  exclude_tags: frontend
  commands:
    lint:
      tags: frontend
      run: yarn lint
    test:
      tags: frontend
      run: yarn test
    check-syntax:
      tags: documentation
      run: yarn check-syntax

複数タグの例

# lefthook.yml

pre-push:
  commands:
    packages-audit:
      tags:
        - frontend
        - security
      run: yarn audit
    gems-audit:
      tags:
        - backend
        - security
      run: bundle audit

# lefthook-local.yml

pre-push:
  exclude_tags:
    - frontend

ローカル限定の除外は lefthook-local.yml で指定することを推奨。

---

exclude

Source: https://lefthook.dev/configuration/exclude

• 型: Array of strings (glob パターン)

ファイルテンプレートで除外するファイルの glob パターンリストを設定する。glob_matcher 設定の影響を受ける。

run オプションにファイルテンプレートなしで exclude を指定した場合、lefthook は pre-commit フックでは {staged_files}、pre-push フックでは {push_files} を自動チェックし、フィルタ後にファイルが残らなければコマンドをスキップする。

Job レベルの除外

pre-commit:
  jobs:
    - name: lint
      glob: "*.rb"
      exclude:
        - config/routes.rb
        - config/application.rb
        - config/initializers/*.rb
        - spec/rails_helper.rb
      run: bundle exec rubocop --force-exclusion -- {staged_files}

Hook レベルの除外

pre-commit:
  exclude:
    - "*/application.rb"
  jobs:
    - name: lint
      run: bundle exec rubocop

---

only

Source: https://lefthook.dev/configuration/only

• 型: Array / String

特定条件下でのみコマンド、スクリプト、またはフック全体の実行を強制する。skip の逆で、同じ条件値を受け入れる。

注意: skip と only の両方の条件が存在する場合、skip が優先される。

ブランチ指定実行

pre-commit:
  only:
    - ref: dev/*
  commands:
    lint:
      run: yarn lint
    test:
      run: yarn test

rebase 時の条件付きコマンド選択

pre-commit:
  commands:
    lint:
      skip: rebase
      run: yarn lint
    test:
      skip: rebase
      run: yarn test
    lint-on-rebase:
      only: rebase
      run: yarn lint-quickly

---

skip

Source: https://lefthook.dev/configuration/skip

• 型: Boolean / Array / String

さまざまな git 状態、ブランチ名、またはカスタムコマンド評価に基づいて条件付きでコマンドやスクリプトの実行を防止する。

指定可能な値

• rebase - rebase 中にスキップ
• merge - merge 中にスキップ
• merge-commit - 現在の HEAD コミットがマージコミットの場合にスキップ
• ref: <branch> - 指定ブランチでスキップ（glob パターンサポート）
• run: <command> - コマンドが正常終了（リターンコード 0）した場合にスキップ

無条件スキップ

pre-commit:
  commands:
    lint:
      skip: true
      run: yarn lint

merge または rebase 中のスキップ

pre-commit:
  commands:
    lint:
      skip:
        - merge
        - rebase
      run: yarn lint

マージコミットでのスキップ

pre-push:
  commands:
    lint:
      skip: merge-commit
      run: yarn lint

ブランチパターンによるフック全体のスキップ

pre-commit:
  skip:
    - ref: main
  commands:
    lint:
      run: yarn lint
    test:
      run: yarn test

コマンド実行に基づくスキップ

pre-commit:
  skip:
    - run: test "${NO_HOOK}" -eq 1
  commands:
    lint:
      run: yarn lint

条件付きスキップの複合例

prepare-commit-msg:
  skip:
    - merge
    - rebase
  commands:
    aiautocommit:
      interactive: true
      run: aiautocommit commit --output-file "{1}"
      env:
        LOG_LEVEL: info
      skip:
        - run: "! which aiautocommit"

フックレベルと個別コマンド/スクリプトレベルの両方で適用可能。

---

setup

Source: https://lefthook.dev/configuration/setup

• 型: Array
• 追加バージョン: lefthook 2.1.2

ジョブの実行前に実行する命令のリスト。テンプレートと Git 引数をサポートする。

設定のマージ時（lefthook-local.yml や extends）、setup 命令はリストの先頭に追加される。

# lefthook.yml

pre-commit:
  setup:
    - run: |
        if ! command -v golangci-lint >/dev/null 2>&1; then
          go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.10.1
        fi
  jobs:
    - run: golangci-lint -- {staged_files}
      glob: "*.go"

---

jobs

Source: https://lefthook.dev/configuration/jobs

• 型: Array
• 追加バージョン: lefthook 1.10.0

タスクを定義する柔軟な方法。コマンドとスクリプトの両方をサポートし、グループ化による高度なフロー制御が可能。

基本使用法

pre-commit:
  jobs:
    - run: yarn lint
    - run: yarn test

名前付き vs 名前なしジョブ

• 名前付きジョブは extends 設定やローカル設定間でマージされる
• 名前なしジョブは定義順に追加される

グループ

• グループは他のジョブを含むことができる
• グループ内で parallel または piped 実行をサポート
• glob、root、exclude オプションはネストされたジョブを含むグループ内のすべてのジョブに適用される

高度な例

pre-commit:
  parallel: true
  jobs:
    - name: migrate
      root: backend/
      glob: "db/migrations/*"
      group:
        piped: true
        jobs:
          - run: bundle install
          - run: rails db:migrate
    - run: yarn lint --fix {staged_files}
      root: frontend/
      stage_fixed: true
    - run: bundle exec rubocop
      root: backend/
    - run: golangci-lint
      root: proxy/
    - script: verify.sh
      runner: bash

Configuration

Remotes

Source: https://lefthook.dev/configuration/remotes

複数のリモート設定を提供して、lefthook の設定を多くのプロジェクトで共有できる。Lefthook は自動的にリモート設定をダウンロードしてローカルの lefthook.yml にマージする。

概要

• リモートリポジトリのルートに基づく相対パスで extends を使用可能
• スクリプトフォルダはリモート設定で提供する場合、リポジトリのルートに配置する必要がある
• シンプルさのため、リモート設定のジョブは他のステップから独立させることを推奨

マージ優先順位

1. ローカルメイン設定 (lefthook.yml) 2. リモート設定 (remotes) 3. ローカルオーバーライド (lefthook-local.yml)

---

git_url

Source: https://lefthook.dev/configuration/git_url

• 型: String (URL)

Git リポジトリへの URL。lefthook が実行されるマシンの権限でアクセスされる。

SSH プロトコル

remotes:
  - git_url: git@github.com:evilmartians/lefthook

HTTPS プロトコル

remotes:
  - git_url: https://github.com/evilmartians/lefthook

---

ref

Source: https://lefthook.dev/configuration/ref

• 型: String (ブランチ名またはタグ名)

リモート設定のオプションのブランチまたはタグ名。

remotes:
  - git_url: git@github.com:evilmartians/lefthook
    ref: v1.0.0

注意: 最初に ref オプションを設定して lefthook install を実行した後に削除すると、lefthook はどのブランチ/タグを ref として使用すべきか判断できない。一度追加したら常に使用すること。

---

refetch

Source: https://lefthook.dev/configuration/refetch

• 型: Boolean
• デフォルト: false

毎回の実行でリモート設定の再取得を強制する。

remotes:
  - git_url: https://github.com/evilmartians/lefthook
    refetch: true

注意: refetch: true は refetch_frequency の設定よりも優先される。

---

refetch_frequency

Source: https://lefthook.dev/configuration/refetch_frequency

• 型: String (always, never, または時間指定 24h, 30m など)
• デフォルト: 未設定

Lefthook がリモート設定を再取得する頻度を指定する。

動作

• always: 毎回の Lefthook 実行時に取得
• 時間形式（例: 24h, 30m）: 指定時間経過後にのみ再取得
• never または未設定: リモート取得なし

取得に失敗した場合、エラーではなく警告が表示される。以前の成功した取得があればそのキャッシュ設定が使用され、なければリモートはスキップされる。

# lefthook.yml

remotes:
  - git_url: https://github.com/evilmartians/lefthook
    refetch_frequency: 24h

---

configs

Source: https://lefthook.dev/configuration/configs

• 型: Array of strings
• デフォルト: [lefthook.yml]

リモートのルートからの設定パスのオプション配列。

単一リモートの複数設定

# lefthook.yml

remotes:
  - git_url: git@github.com:evilmartians/lefthook
    ref: v1.0.0
    configs:
      - examples/ruby-linter.yml
      - examples/test.yml

複数リモートの複数設定

# lefthook.yml

remotes:
  - git_url: git@github.com:org/lefthook-configs
    ref: v1.0.0
    configs:
      - examples/ruby-linter.yml
      - examples/test.yml
  - git_url: https://github.com/org2/lefthook-configs
    configs:
      - lefthooks/pre_commit.yml
      - lefthooks/post_merge.yml
  - git_url: https://github.com/org3/lefthook-configs
    ref: feature/new
    configs:
      - configs/pre-push.yml

Script Settings

Source: https://lefthook.dev/configuration

<source_dir>/<hook-name>/ ディレクトリに配置される独自の実行可能スクリプトの設定。スクリプトはプロジェクトルートから実行される。

Scripts

Source: https://lefthook.dev/configuration/Scripts

セットアップ手順

1. lefthook add -d <hook-name> を実行 2. .lefthook/<hook-name>/your-script.sh でスクリプトファイルを編集 3. lefthook.yml で設定

設定プロパティ

設定例

# lefthook.yml

commit-msg:
  scripts:
    "template_checker":
      runner: bash

コミットメッセージバリデータの例

# .lefthook/commit-msg/template_checker

INPUT_FILE=$1
START_LINE=`head -n1 $INPUT_FILE`
PATTERN="^(TICKET)-[[:digit:]]+: "
if ! [[ "$START_LINE" =~ $PATTERN ]]; then
  echo "Bad commit message, see example: TICKET-123: some text"
  exit 1
fi

commit-msg:
  scripts:
    "template_checker":
      runner: bash

---

script

Source: https://lefthook.dev/configuration/script

• 型: String (ファイル名)

lefthook ジョブ内で実行するスクリプトファイル名を指定する。ルールは scripts と同じ。

# lefthook.yml

pre-commit:
  jobs:
    - script: linter.sh
      runner: bash

# .lefthook/pre-commit/linter.sh

echo "Everything is OK"

runner オプションはスクリプトのインタプリタを定義するため、script と併せて指定する必要がある。

---

runner

Source: https://lefthook.dev/configuration/runner

• 型: String

スクリプトファイルを実行するコマンドを指定する。<runner> <path-to-script> の形式で呼び出される。

# lefthook.yml

pre-commit:
  scripts:
    "lint.js":
      runner: node
    "check.go":
      runner: go run

• 同じフック内で異なるスクリプトに異なるランナーを使用可能
• 一般的なランナー: node, ruby, python, bash, sh, go run
• ランナーコマンドは実行時にシステムの PATH で利用可能である必要がある

Source Dir

Source: https://lefthook.dev/configuration

スクリプトファイルのディレクトリ設定。

source_dir

Source: https://lefthook.dev/configuration/source_dir

• 型: String (ディレクトリパス)
• デフォルト: .lefthook/

スクリプトファイルのディレクトリを変更する。スクリプトファイルディレクトリは git フック名のフォルダを含み、その中にスクリプトファイルが配置される。

ディレクトリ構造例

.lefthook/
├── pre-commit/
│   ├── lint.sh
│   └── test.py
└── pre-push/
    └── check-files.rb

# lefthook.yml

source_dir: .my-hooks/

---

source_dir_local

Source: https://lefthook.dev/configuration/source_dir_local

• 型: String (ディレクトリパス)
• デフォルト: .lefthook-local/

バージョン管理されないローカルスクリプトファイルのディレクトリを指定する。lefthook-local.yml 設定ファイルがあり、そこで別のスクリプトを参照したい場合に有用。

# lefthook-local.yml

source_dir_local: .my-local-hooks/

Commitlint and Commitizen with Lefthook

Source: https://lefthook.dev/examples/commitlint

commitlint（コミットメッセージの検証）と Commitizen（対話的なコミットメッセージ生成）を Lefthook と統合する方法を説明します。

依存パッケージのインストール

commitlint（コミットメッセージのリント）

yarn add -D @commitlint/cli @commitlint/config-conventional

Commitizen（対話的コミットメッセージ生成）

yarn add -D commitizen cz-conventional-changelog

設定

commitlint の設定

commitlint.config.js を作成し、Conventional Commits の規約を使用するように設定します:

module.exports = {
  extends: ['@commitlint/config-conventional']
};

Commitizen の設定

package.json に Commitizen の設定を追加し、Conventional Changelog アダプターを指定します:

{
  "config": {
    "commitizen": {
      "path": "cz-conventional-changelog"
    }
  }
}

Lefthook の設定

# lefthook.yml

prepare-commit-msg:
  commands:
    commitizen:
      interactive: true
      run: yarn run cz --hook
      env:
        LEFTHOOK: 0

commit-msg:
  commands:
    commitlint:
      run: yarn run commitlint --edit {1}

フックの説明

prepare-commit-msg フック

• commitizen コマンドが対話的に実行され、コミットメッセージの生成を支援する
• interactive: true で対話モードを有効化
• LEFTHOOK: 0 環境変数により、Commitizen 実行中の Lefthook の再帰的実行を防止

commit-msg フック

• commitlint コマンドがコミットメッセージを検証する
• {1} はコミットメッセージファイルのパスに展開される

使用方法

• Commitizen を使う場合: メッセージ引数なしで git commit を実行すると、対話的にコミットメッセージを生成できる
• commitlint のみ使う場合: git commit -m "メッセージ" で直接メッセージを指定し、commitlint が検証する

Filters（ファイルフィルタリング）

Source: https://lefthook.dev/examples/filters

フックに渡されるファイルをフィルタリングするためのオプションについて説明します。

利用可能なフィルタオプション

フックに渡されるファイルは、以下のオプションでフィルタリングできます:

• `glob` - ファイル名のパターンマッチング
• `exclude` - 除外パターン
• `file_types` - ファイルタイプによるフィルタ
• `root` - ルートディレクトリの指定

設定例

# lefthook.yml

pre-commit:
  commands:
    lint:
      run: yarn lint {staged_files} --fix
      glob: "*.{js,ts}"
      root: frontend
      exclude:
        - *.config.js
        - *.config.ts
      file_types:
        - not executable

フィルタリングの動作例

入力ファイル（ステージされたファイル）

• backend/asset.js
• frontend/src/index.ts
• frontend/bin/cli.js（実行可能ファイル）
• frontend/eslint.config.js
• frontend/README.md

フィルタリング後の結果

yarn lint frontend/src/index.ts --fix

フィルタの適用順序

各フィルタは以下のようにファイルを絞り込みます:

1. `root: frontend` - frontend ディレクトリ外のファイル（backend/asset.js）を除外 2. *`glob: ".{js,ts}"** - JavaScript/TypeScript 以外のファイル（frontend/README.md）を除外 3. **exclude** - 設定ファイル（frontend/eslint.config.js）を除外 4. **file_types: not executable** - 実行可能ファイル（frontend/bin/cli.js`）を除外

最終的に frontend/src/index.ts のみがコマンドに渡されます。

lefthook-local.yml

Source: https://lefthook.dev/examples/lefthook-local

lefthook-local.yml はメインの設定ファイル（lefthook.yml）をオーバーライドおよび拡張するためのローカル設定ファイルです。

Tip: lefthook-local.yml を ~/.gitignore に追加しておけば、すべてのプロジェクトでローカル専用のオーバーライドを持つことができます。

基本例

メインの設定ファイル（lefthook.yml）

pre-commit:
  commands:
    lint:
      run: bundle exec rubocop -- {staged_files}
      glob: "*.rb"
    check-links:
      run: lychee -- {staged_files}

ローカルオーバーライド（lefthook-local.yml）

pre-commit:
  parallel: true
  commands:
    lint:
      run: docker-compose run backend {cmd}
    check-links:
      skip: true

post-merge:
  files: "git diff-tree -r --name-only --no-commit-id ORIG_HEAD HEAD"
  commands:
    dependencies:
      glob: "Gemfile*"
      run: docker-compose run backend bundle install

マージ結果

上記の 2 つのファイルがマージされると、以下のような最終設定になります:

• pre-commit フックは parallel: true で並列実行されるようになる
• lint コマンドは docker-compose run backend {cmd} でラップされる（{cmd} は元の bundle exec rubocop -- {staged_files} に展開される）
• check-links コマンドはスキップされる
• 新しい post-merge フックが追加され、Gemfile の変更時に bundle install を実行する

主なポイント

• ローカル設定はメイン設定をオーバーライドして拡張できる
• {cmd} プレースホルダーを使って元のコマンドをラップできる
• skip: true で特定のコマンドを無効化できる
• 新しいフックやコマンドをローカルのみで追加できる

Examples

Remotes（リモート設定の共有）

Source: https://lefthook.dev/examples/remotes

remotes 機能を使って、他の Git リポジトリから設定ファイルを取得・共有する方法を説明します。

概要

remotes 機能により、他の Git リポジトリの設定を利用できます。Lefthook はリモートの設定ファイルを自動的にダウンロードし、既存の設定にマージします。

設定例

remotes:
  - git_url: https://github.com/evilmartians/lefthook
    configs:
      - examples/remote/ping.yml

主なポイント

• `git_url` - 設定ファイルを取得するリモート Git リポジトリの URL
• `configs` - リポジトリ内の設定ファイルのパス（複数指定可能）
• リモートの設定ファイルは自動的にダウンロードされ、ローカルの設定にマージされる
• チーム間やプロジェクト間で共通の Git フック設定を共有するのに便利

Skip or Run on Condition（条件付きスキップ・実行）

Source: https://lefthook.dev/examples/skip

フックやコマンドを特定の条件に基づいてスキップまたは実行する方法を説明します。

設定例

pre-commit:
  only:
    - ref: dev/*
  commands:
    lint:
      run: yarn lint {staged_files} --fix
      glob: "*.{ts,js}"
    test:
      run: yarn test

pre-push:
  commands:
    test:
      run: yarn test
      skip:
        - run: test "$NO_TEST" -eq 1
    lint:
      run: yarn lint
      only:
        - ref: main

各設定の説明

pre-commit フック

• *`only: ref: dev/** - dev/` プレフィックスで始まるブランチでコミットする場合にのみ実行される
• lint と test の両コマンドは、このブランチ条件を満たす場合にのみ実行される

pre-push フック

test コマンド

• `skip: run: test "$NO_TEST" -eq 1` - 環境変数 NO_TEST が 1 に設定されている場合にスキップされる
• NO_TEST=1 git push のように使用することで、テストをスキップしてプッシュできる

lint コマンド

• `only: ref: main` - main ブランチにプッシュする場合にのみ実行される

主なポイント

• `only` - 条件を満たす場合にのみ実行する（ホワイトリスト方式）
• `skip` - 条件を満たす場合にスキップする（ブラックリスト方式）
• `ref` - ブランチ名によるフィルタリング（glob パターン対応）
• `run` - シェルコマンドの終了コードによる条件判定（0 で true）

Stage fixed files（修正ファイルの自動ステージング）

Source: https://lefthook.dev/examples/stage_fixed

リンターがファイルを自動修正した場合、修正されたファイルを自動的にステージングしてコミットに含める方法を説明します。

概要

リンターが変更を修正することがあり、通常はそれらを自動的にコミットに含めたいケースがあります。stage_fixed 設定オプションを使うことで、修正されたファイルの自動ステージングを有効にできます。

設定例

# lefthook.yml

pre-commit:
  commands:
    lint:
      run: yarn lint {staged_files} --fix
      stage_fixed: true

主なポイント

• stage_fixed: true を指定すると、コマンド実行後に修正されたファイルが自動的に git add される
• この機能は pre-commit フックのコンテキストでのみ動作する
• リンターの --fix オプションと組み合わせて使用するのが一般的なパターン

Wrap commands（コマンドのラッピング）

Source: https://lefthook.dev/examples/wrap-commands

ローカル設定ファイルを使って、メインの設定ファイルで定義されたコマンドをラップする方法を説明します。dip（docker-compose run に類似したツール）を使った例で示します。

メインの設定ファイル（lefthook.yml）

pre-commit:
  jobs:
    - name: rubocop
      run: bundle exec rubocop -A -- {staged_files}

pre-commit フックで Rubocop を自動修正モード（-A）で実行し、ステージされたファイルを対象にします。

ローカル設定ファイル（lefthook-local.yml）

pre-commit:
  jobs:
    - name: rubocop
      run: dip {cmd}

ローカル設定で {cmd} プレースホルダーを使うことで、元のコマンドを dip でラップして実行します。

動作の仕組み

1. メイン設定の rubocop コマンドは bundle exec rubocop -A -- {staged_files} として定義されている 2. ローカル設定で run: dip {cmd} と指定すると、{cmd} が元のコマンドに展開される 3. 最終的に実行されるコマンドは dip bundle exec rubocop -A -- {staged_files} となる

ツール参考

• dip - Docker 化された開発体験を提供するツール。docker-compose run に似た機能を持つ。

Alpine Linux でのインストール

Source: https://lefthook.dev/installation/alpine

インストール手順

Alpine Linux で APK パッケージを使用して Lefthook をインストールします。

1. 前提パッケージのインストール

sudo apk add --no-cache bash curl

2. リポジトリのセットアップ

curl -1sLf 'https://dl.cloudsmith.io/public/evilmartians/lefthook/setup.alpine.sh' | sudo -E bash

3. パッケージのインストール

sudo apk add lefthook

補足情報

パッケージリポジトリは Cloudsmith でホストされています。詳細な設定手順については Cloudsmith のリポジトリ設定ページ を参照してください。

Arch Linux でのインストール

Source: https://lefthook.dev/installation/arch

AUR パッケージの選択肢

Arch User Repository (AUR) には2つのパッケージが用意されています。

1. lefthook - ソースコードからコンパイルしてインストール 2. lefthook-bin - コンパイル済みバイナリをインストール

インストールコマンド

yay AUR ヘルパーを使用する場合:

# ソースからコンパイルする場合
yay -S lefthook

# コンパイル済みバイナリをインストールする場合
yay -S lefthook-bin

パッケージの違い

• ソースビルド版 (lefthook): インストール時にコンパイルが必要ですが、最新のソースからビルドされます
• バイナリ版 (lefthook-bin): コンパイル済みのバイナリを使用するため、インストールが高速です

deb パッケージでのインストール

Source: https://lefthook.dev/installation/deb

インストール手順

Debian / Ubuntu 系ディストリビューションで APT パッケージを使用して Lefthook をインストールします。

1. リポジトリのセットアップ

curl -1sLf 'https://dl.cloudsmith.io/public/evilmartians/lefthook/setup.deb.sh' | sudo -E bash

2. パッケージのインストール

sudo apt install lefthook

補足情報

パッケージリポジトリは Cloudsmith でホストされています。詳細な設定手順については Cloudsmith のリポジトリ設定ページ を参照してください。

Devbox でのインストール

Source: https://lefthook.dev/installation/devbox

概要

Lefthook は Nix パッケージ として公式リポジトリに存在するため、Devbox 環境への追加が簡単に行えます。

インストールコマンド

devbox add lefthook@latest

注意事項

Devbox 向けの Lefthook 統合はコミュニティによってメンテナンスされており、Lefthook コアチームの公式サポート対象外です。Devbox 固有のインストール問題については、Lefthook メンテナーから直接的なサポートを受けることができない場合があります。

Go でのインストール

Source: https://lefthook.dev/installation/go

前提条件

Go でのインストールには、Go バージョン 1.26 以上が必要です。

インストール方法

グローバルインストール

Go パッケージとしてシステム全体にインストールする場合は、以下のコマンドを実行します。

go install github.com/evilmartians/lefthook/v2@v2.1.4

この方法では、どのプロジェクトからでもツールを使用できるようになります。

プロジェクトレベルのツールインストール

特定のプロジェクト内にツール依存として追加する場合は、以下のコマンドを使用します。

go get -tool github.com/evilmartians/lefthook/v2

この方法では、プロジェクトのツールチェーンにスコープが限定されます。

バージョン情報

上記のインストール例では Lefthook v2.1.4 を参照しています。最新バージョンについては GitHub リリースページ を確認してください。

Homebrew でのインストール

Source: https://lefthook.dev/installation/homebrew

インストールコマンド

macOS および Linux で Homebrew を使用して Lefthook をインストールするには、以下のコマンドを実行します。

brew install lefthook

手動インストール

Source: https://lefthook.dev/installation/manual

インストール手順

最新リリース からお使いのシステムに対応したバイナリをダウンロードし、手動でインストールします。

手順

1. GitHub リリースページ にアクセスする 2. お使いの OS・アーキテクチャに対応したバイナリをダウンロードする 3. ダウンロードしたバイナリを $PATH の通ったディレクトリに配置する 4. 実行権限を付与する（macOS / Linux の場合）

補足

パッケージマネージャーを使用した代替インストール方法も多数用意されています。詳細は インストール概要 を参照してください。

mise でのインストール

Source: https://lefthook.dev/installation/mise

インストールコマンド

mise use lefthook@latest

Mise バージョンマネージャーを使用して Lefthook をインストールします。プロジェクト内でツール依存として管理することが可能です。

注意事項

Lefthook の mise プラグインはコミュニティによってメンテナンスされています。Lefthook チームは mise 固有のインストール問題について直接的なサポートを提供できない場合があります。

参考リンク

• mise 公式リポジトリ

Node.js (npm) でのインストール

Source: https://lefthook.dev/installation/node

インストールコマンド

各パッケージマネージャーに対応したインストールコマンドは以下の通りです。

npm install --save-dev lefthook

yarn add --dev lefthook

pnpm add -D lefthook

パッケージの選択肢

Lefthook は3つの NPM パッケージとして配布されています。

1. lefthook（推奨）

お使いのシステムに対応した単一の実行ファイルをインストールします。

npm install --save-dev lefthook

2. @evilmartians/lefthook（レガシー）

すべての OS 向けの実行ファイルをインストールします。

npm install --save-dev @evilmartians/lefthook

3. @evilmartians/lefthook-installer（レガシー）

インストール時に適切な実行ファイルを取得します。

npm install --save-dev @evilmartians/lefthook-installer

pnpm 利用時の重要な設定

pnpm をパッケージマネージャーとして使用する場合、postinstall スクリプトが正しく実行されフックが正常にインストールされるよう、以下の設定が必要です。

• pnpm-workspace.yaml の onlyBuiltDependencies に lefthook を追加する
• ルートの package.json の pnpm.onlyBuiltDependencies に lefthook を追加する

インストール概要

Source: https://lefthook.dev/install

Lefthook について

Lefthook はスタンドアロンで依存関係のないバイナリとして配布される Git フックマネージャーです。Evil Martians によってメンテナンスされており、MIT ライセンスで配布されています。

インストール方法一覧

パッケージマネージャー経由

以下のパッケージマネージャーからインストールできます。

• Ruby (gem)
• NPM (Node.js)
• Go
• Python (pip / uv / pipx)
• Swift (SwiftPM / Mint)
• Homebrew (macOS / Linux)
• Winget (Windows)
• Scoop (Windows)
• deb (Debian / Ubuntu)
• RPM (CentOS / Fedora)
• Alpine (APK)
• Arch Linux (AUR)
• Snap
• Devbox
• Mise

手動インストール

パッケージマネージャーを使わずに直接インストールする場合は、リリースページ からお使いの OS・アーキテクチャに対応したバイナリをダウンロードし、$PATH の通ったディレクトリに配置してください。

セルフアップデート

インストール済みの Lefthook を最新版に更新するには、以下のコマンドを実行します。

lefthook self-update

主な機能

• フックの管理と実行戦略
• ファイルフィルタリングと glob パターン
• コマンドのパイプ処理と並列実行
• インストール・検証・管理のための CLI コマンド
• 環境変数によるカスタマイズ
• リモート設定のサポート

リンク

• リポジトリ: https://github.com/evilmartians/lefthook

Python でのインストール

Source: https://lefthook.dev/installation/python

インストール方法

pip（標準）

python -m pip install --user lefthook

現在のユーザー向けにパッケージをローカルインストールします。

uv

uv add --dev lefthook

開発依存として統合する方法です。

pipx

pipx install lefthook

コマンドラインツールとして分離された環境にインストールする方法です。

installation

RPM パッケージでのインストール

Source: https://lefthook.dev/installation/rpm

インストール手順

CentOS / Fedora 等の RPM ベースのディストリビューションに Lefthook をインストールします。

1. リポジトリのセットアップ

curl -1sLf 'https://dl.cloudsmith.io/public/evilmartians/lefthook/setup.rpm.sh' | sudo -E bash

2. パッケージのインストール

sudo yum install lefthook

補足情報

RPM パッケージは Cloudsmith のオープンソースリポジトリサービスでホストされています。詳細な設定手順については Cloudsmith のリポジトリ設定ページ を参照してください。

Ruby (gem) でのインストール

Source: https://lefthook.dev/installation/ruby

インストール方法

Gemfile 経由（開発環境向け）

プロジェクトの Gemfile に以下を追加します。

# Gemfile

group :development do
  gem "lefthook", require: false
end

その後 bundle install を実行してインストールします。

グローバルインストール

gem コマンドで直接インストールすることも可能です。

gem install lefthook

トラブルシューティング

lefthook: command not found エラーが発生した場合は、$PATH の設定を確認してください。インストール後にターミナルセッションを再起動すると、新しいコマンドが利用可能になります。

Scoop でのインストール

Source: https://lefthook.dev/installation/scoop

インストールコマンド

Windows 上で Scoop を使用して Lefthook をインストールするには、以下のコマンドを実行します。

scoop install lefthook

Snap でのインストール

Source: https://lefthook.dev/installation/snap

インストールコマンド

Linux 上で Snap を使用して Lefthook をインストールするには、以下のコマンドを実行します。

snap install --classic lefthook

--classic フラグにより、classic confinement モードでインストールされます。

Swift でのインストール

Source: https://lefthook.dev/installation/swift

概要

Swift での Lefthook の統合はコミュニティのラッパープラグインを通じて提供されています。Swift ラッパープラグインは こちら で公開されています。

インストール方法

Swift Package Manager

Package.swift ファイルに以下の依存関係を追加します。

.package(url: "https://github.com/csjones/lefthook-plugin.git", exact: "2.1.4"),

Mint パッケージマネージャー

Mint を使用してプラグインを実行することもできます。

mint run csjones/lefthook-plugin

参考情報

Swift Package Manager または Mint パッケージマネージャーのいずれかを使って、Swift プロジェクトに Lefthook を導入できます。

Winget でのインストール

Source: https://lefthook.dev/installation/winget

インストールコマンド

Windows Package Manager (Winget) を使用して Lefthook をインストールするには、以下のコマンドを実行します。

winget install evilmartians.lefthook

CLI コマンド

Source: https://lefthook.dev/usage/commands/

Lefthook の CLI コマンド一覧。

lefthook install

Source: https://lefthook.dev/usage/commands/install

lefthook install コマンドは Git hooks の設定システムを初期化する。lefthook.yml 設定ファイルがまだ存在しない場合は空のファイルを作成し、設定されたフックを Git hooks ディレクトリにインストールする。

使い方

lefthook install [<hook-1> <hook-2> ...]

特定のフックのインストール

フック名を引数として指定することで、特定のフックのみをインストールできる:

lefthook install <hook-1> <hook-2> ...

注意事項

• 設定の永続性: lefthook.yml を変更した後にフックを再インストールする必要はない。設定ファイルは Git hook が実行されるたびに自動的に読み込まれる。
• 自動インストール: NPM パッケージ lefthook を使用するプロジェクトでは、postinstall スクリプトによりフックが自動的にインストールされる。その他のプロジェクトでは、リポジトリをクローンした後にこのコマンドを実行する。

lefthook uninstall

Source: https://lefthook.dev/usage/commands/uninstall

lefthook uninstall コマンドは lefthook によってインストールされた Git hooks をすべて削除する。

使い方

lefthook uninstall

説明

リポジトリ内で lefthook が .git/hooks ディレクトリに設定したフック構成をクリーンアップする。

注意事項

• lefthook を通じてインストールされたフックのみを対象とする
• このコマンド実行後、lefthook が管理する Git hooks は実行されなくなる
• lefthook の設定ファイルには影響しない。Git リポジトリからインストール済みフックのみを削除する

lefthook run

Source: https://lefthook.dev/usage/commands/run

指定されたフックに設定されたコマンドとスクリプトを実行する。インストール済みの Git hooks は暗黙的に lefthook run を呼び出す。

使い方

lefthook run <hook_name> [options]

設定例

# lefthook.yml

pre-commit:
  jobs:
    - name: lint
      run: yarn lint --fix {staged_files}

test:
  jobs:
    - name: test
      run: yarn test

実行例

# まずフックをインストール
$ lefthook install

# 特定のフックを実行
$ lefthook run test                    # 'yarn test' を実行
$ lefthook run pre-commit              # 設定された pre-commit フックを実行

# 自動実行
$ git commit                           # pre-commit フックが自動的に実行される

オプション

ジョブ選択

--job フラグで実行するジョブを指定する（複数指定可）:

$ lefthook run pre-commit --job lints --job pretty --tag checks

ファイル指定

{staged_files} のようなファイルテンプレートをカスタムファイルリストで上書きする:

# すべてのファイルを使用
$ lefthook run pre-commit --all-files

# 個別のファイルを指定
$ lefthook run pre-commit --file file1.js --file file2.js

注意: 両方のオプションが指定された場合、--all-files は無視され、明示的に指定されたファイルが優先される。

lefthook add

Source: https://lefthook.dev/usage/commands/add

lefthook add コマンドは指定された Git hook をインストールする。--dirs フラグを使用すると、必要なディレクトリ構造（.git/hooks/<hook name>/）が存在しない場合に作成する。

使い方

lefthook add <hook-name> [OPTIONS]

オプション

• --dirs -- ディレクトリ .git/hooks/<hook name>/ が存在しない場合に作成する。スクリプトを設定に追加する前に使用することを推奨。

例

フックをディレクトリ作成付きでインストール:

$ lefthook add pre-push --dirs

lefthook.yml でフックを設定:

pre-push:
  jobs:
    - script: "audit.sh"
      runner: bash

スクリプトファイルを編集:

$ vim .lefthook/pre-push/audit.sh

設定後、git push を実行すると pre-push フックが実行され、指定された bash スクリプトが実行される。

注意事項

フックのインストールは Git リポジトリのフックシステムと統合される。フックの動作とコマンドの設定は lefthook.yml ファイルで行い、スクリプトは通常 .lefthook/ ディレクトリ構造に保存する。

lefthook validate

Source: https://lefthook.dev/usage/commands/validate

lefthook validate コマンドは lefthook の設定の正当性をチェックする。

使い方

lefthook validate

説明

lefthook の GitHub リポジトリから取得した JSON スキーマを使用して、設定ファイルに対してバリデーションチェックを実行する。

関連コマンド

• `lefthook dump`: 完全なバリデーション済み設定を表示する
• `lefthook install`: 設定のバリデーション後に Git hooks をインストールする
• `lefthook check-install`: フックのインストール状態を確認する

lefthook dump

Source: https://lefthook.dev/usage/commands/dump

lefthook dump コマンドは、すべてのセカンダリ設定をマージした後の完全な設定を表示する。

使い方

lefthook dump

説明

lefthook が実際に使用する設定を表示する。設定は以下の複数のソースから構成される場合がある:

• プライマリ設定ファイル（lefthook.yml）
• リモート設定
• 拡張設定
• ローカルオーバーライド（lefthook-local.yml）

注意事項

このコマンドはデバッグや検証に有用で、すべての設定ソースが結合・処理された後の最終的なマージ済み設定を確認できる。

lefthook check-install

Source: https://lefthook.dev/usage/commands/check-install

lefthook check-install コマンドは Git hooks がインストールされ、同期されているかどうかを確認する。

使い方

lefthook check-install

戻り値

• 0 -- フックがインストールされ、同期されている
• 1 -- フックがインストールされていないか、同期が必要

注意事項

CI/CD パイプラインや自動化スクリプトで、フックのセットアップがプロジェクトの設定と一致していることを確認するのに有用。

lefthook self-update

Source: https://lefthook.dev/usage/commands/self-update

lefthook self-update コマンドはバイナリを GitHub 上の最新リリースに更新する。

使い方

lefthook self-update

利用条件

このコマンドは以下の方法で lefthook をインストールした場合にのみ使用可能:

• ソースコードからインストール
• GitHub Releases からバイナリを直接ダウンロード

パッケージマネージャー（npm, Ruby gem, Homebrew など）でインストールした場合は、そのパッケージマネージャーの更新メカニズムを使用すること。

環境変数

Source: https://lefthook.dev/usage/envs/

Lefthook の動作を制御する環境変数。

LEFTHOOK

Source: https://lefthook.dev/usage/envs/LEFTHOOK

LEFTHOOK 環境変数は、git コマンド実行時に lefthook を実行するかどうかを制御する。

値

• 0 または false -- lefthook の実行を無効化
• 1 または true -- lefthook の実行を有効化（CI 環境で有用）

使用例

単一のコマンドでフック実行をスキップ:

LEFTHOOK=0 git commit -am "Lefthook skipped"

CI 環境で lefthook を有効化:

LEFTHOOK=1 npm install
LEFTHOOK=1 yarn install
LEFTHOOK=1 pnpm install

注意事項

一時的にフックのバリデーションをバイパスする場合や、自動的な CI 検出により無効化される可能性がある CI パイプラインでフックの実行を保証する場合に有用。

LEFTHOOK_VERBOSE

Source: https://lefthook.dev/usage/envs/LEFTHOOK_VERBOSE

LEFTHOOK_VERBOSE 環境変数は Lefthook 実行時の詳細出力を有効にする。

値

• 1 -- verbose モードを有効化
• true -- verbose モードを有効化

使用例

LEFTHOOK_VERBOSE=1 lefthook run pre-commit

注意事項

フックの設定のデバッグやフック実行フローの理解に有用。Lefthook がフック実行時に何を行っているかの詳細情報を確認できる。

LEFTHOOK_OUTPUT

Source: https://lefthook.dev/usage/envs/LEFTHOOK_OUTPUT

LEFTHOOK_OUTPUT 環境変数は、フック実行時に出力される情報を制御する。出力の詳細度をカスタマイズしたり、エラー以外のメッセージを無効にしたりできる。

使い方

出力値のリストを設定:

LEFTHOOK_OUTPUT={list of output values}

エラー以外のすべての出力を無効化:

LEFTHOOK_OUTPUT=false

使用例

$ LEFTHOOK_OUTPUT=summary lefthook run pre-commit
summary: (done in 0.52 seconds)
✔️  lint

関連設定

利用可能な出力値と設定オプションの詳細については、`output` 設定ドキュメントを参照。

LEFTHOOK_CONFIG

Source: https://lefthook.dev/usage/envs/LEFTHOOK_CONFIG

LEFTHOOK_CONFIG 環境変数はメインの lefthook 設定ファイルの場所をオーバーライドする。

使い方

LEFTHOOK_CONFIG=~/global_lefthook.yml

注意事項

• この変数でメイン設定をオーバーライドしても、他の設定ソースの読み込みは妨げられない
• ローカル設定、extends で指定された設定、リモート設定は引き続き処理される
• ホームディレクトリパス（~）の使用例が示されているが、任意の有効なファイルパスが使用可能

ユースケース

複数のプロジェクトにわたってグローバルな lefthook 設定を維持しつつ、ローカル設定や extends によるプロジェクト固有のオーバーライドを許可する場合に有用。

LEFTHOOK_EXCLUDE

Source: https://lefthook.dev/usage/envs/LEFTHOOK_EXCLUDE

LEFTHOOK_EXCLUDE 環境変数は、タグまたはコマンド名に基づいて特定のコマンドやスクリプトを git hook 実行時にスキップする。

構文

LEFTHOOK_EXCLUDE={list of tags or command names to be excluded}

使用例

LEFTHOOK_EXCLUDE=ruby,security,lint git commit -am "Skip some tag checks"

この例では、ruby、security、lint のタグが付いたフック（またはそれらの名前を持つコマンド）がコミット操作時の実行から除外される。

注意事項

• 設定ファイルを変更せずに一時的に特定のチェックをバイパスする場合に有用
• 除外は変数が設定された単一のコマンド呼び出しにのみ適用される
• タグベースとコマンド名ベースの両方の除外がサポートされている

関連設定

静的な設定ファイルによる同様の機能については、`exclude_tags` 設定オプションを参照。

CLICOLOR_FORCE

Source: https://lefthook.dev/usage/envs/CLICOLOR_FORCE

CLICOLOR_FORCE 環境変数は lefthook とそのすべてのサブコマンドでカラー出力を有効にする。

値

• true -- カラー出力を有効化

使用例

CLICOLOR_FORCE=true

注意事項

ターミナル環境が通常カラーをサポートしないかどうかに関係なく、lefthook がカラー出力を表示するよう強制する。CI/CD パイプラインやカラーサポートが自動検出されない可能性のある自動化環境で有用。

NO_COLOR

Source: https://lefthook.dev/usage/envs/NO_COLOR

NO_COLOR 環境変数は lefthook とそのすべてのサブコマンドでカラー出力を無効にする。

値

• true -- カラー出力を無効化

使用例

NO_COLOR=true

注意事項

NO_COLOR=true が設定されると、lefthook は自身の操作およびフック実行時に呼び出すすべてのサブコマンドでカラー出力を抑制する。

CI

Source: https://lefthook.dev/usage/envs/CI

CI 環境変数は Lefthook の NPM パッケージにおける CI 環境でのフックインストール動作を制御する。

説明

CI=true が設定されている場合、Lefthook は NPM の postinstall スクリプト実行時に Git hooks の自動インストールを抑制する。CI/CD パイプラインでは通常フックのインストールが不要なため、これが有用。

デフォルトの動作

ほとんどの CI システムは自動的に CI=true を設定する。CI プラットフォームが設定しない場合は、不要なフックインストールを防ぐために手動で設定する必要がある。

使用例

CI=true npm install
CI=true yarn install
CI=true pnpm install

オーバーライド

CI=true が設定されている場合でもフックをインストールする必要がある場合は、以下で動作をオーバーライドできる:

LEFTHOOK=1

または

LEFTHOOK=true

これにより、CI 環境がアクティブであっても postinstall スクリプト中のフックインストールが実行される。

Usage

Auto-fix and Stage

Automatically fix lint errors and re-stage the corrected files so they are included in the commit.

# lefthook.yml

pre-commit:
  commands:
    lint:
      glob: "*.{js,ts,jsx,tsx}"
      run: yarn eslint --fix {staged_files}
      stage_fixed: true
    style:
      glob: "*.{css,scss}"
      run: yarn stylelint --fix {staged_files}
      stage_fixed: true

Notes

• stage_fixed: true runs git add on the affected files after the command completes
• Only works in the pre-commit hook context
• Combine with the linter's --fix flag; without --fix the command modifies nothing and staging is a no-op
• glob and exclude filters are respected when determining which files to re-stage

Basic Setup

Install lefthook and configure a pre-commit hook that runs a linter on staged files.

# lefthook.yml

pre-commit:
  commands:
    lint:
      glob: "*.{js,ts,jsx,tsx}"
      run: yarn eslint {staged_files}

# Install hooks into .git/hooks/
lefthook install

# Verify configuration is valid
lefthook validate

Notes

• lefthook install reads lefthook.yml and writes hook scripts into .git/hooks/
• {staged_files} expands to the list of files staged for the commit; the command is skipped if the list is empty after filtering
• glob filters which staged files are passed to the command; non-matching files are excluded
• To skip hooks temporarily: LEFTHOOK=0 git commit

Commitlint Integration

Validate commit messages against Conventional Commits using commitlint, with optional interactive message generation via Commitizen.

# Install dependencies
yarn add -D @commitlint/cli @commitlint/config-conventional commitizen cz-conventional-changelog

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional']
};

// package.json (commitizen adapter)
{
  "config": {
    "commitizen": {
      "path": "cz-conventional-changelog"
    }
  }
}

# lefthook.yml

prepare-commit-msg:
  commands:
    commitizen:
      interactive: true
      run: yarn run cz --hook
      env:
        LEFTHOOK: 0

commit-msg:
  commands:
    commitlint:
      run: yarn run commitlint --edit {1}

Notes

• {1} in commit-msg expands to the path of the temporary commit message file passed by Git
• interactive: true on commitizen allows the CLI prompt to receive keyboard input
• LEFTHOOK: 0 in the prepare-commit-msg env prevents lefthook from re-triggering recursively when Commitizen calls git commit
• To bypass Commitizen and write a message directly: git commit -m "fix: typo"

Conditional Skip

Skip or restrict hook execution based on branch name, Git state, or environment variable.

# lefthook.yml

pre-commit:
  only:
    - ref: dev/*          # run only on branches matching dev/*
  commands:
    lint:
      glob: "*.{ts,js}"
      run: yarn lint {staged_files} --fix
      skip:
        - merge           # skip during merge commits
        - rebase          # skip during interactive rebase

pre-push:
  commands:
    test:
      run: yarn test
      skip:
        - run: test "$NO_TEST" -eq 1   # skip when NO_TEST=1 is exported
    lint:
      run: yarn lint
      only:
        - ref: main       # run only when pushing to main

Notes

• only is a whitelist: the command runs only when the condition matches
• skip is a blacklist: the command is skipped when the condition matches; skip takes precedence over only if both are set
• ref supports glob patterns (e.g., release/*, feat/**)
• The run condition evaluates a shell command; exit code 0 means "skip"
• Hook-level only/skip applies to all commands in that hook; command-level settings apply individually

Local Override

Use lefthook-local.yml to override or extend the shared configuration without modifying the committed file.

# lefthook.yml  (committed to repository)

pre-commit:
  commands:
    lint:
      glob: "*.rb"
      run: bundle exec rubocop -- {staged_files}
    check-links:
      run: lychee -- {staged_files}

# lefthook-local.yml  (git-ignored, per-developer)

pre-commit:
  parallel: true
  commands:
    lint:
      run: docker-compose run backend {cmd}   # {cmd} expands to the original run value
    check-links:
      skip: true

post-merge:
  files: "git diff-tree -r --name-only --no-commit-id ORIG_HEAD HEAD"
  commands:
    dependencies:
      glob: "Gemfile*"
      run: docker-compose run backend bundle install

Notes

• Add lefthook-local.yml to ~/.gitignore (global) so it is never accidentally committed
• {cmd} in run expands to the original command string from lefthook.yml, enabling wrapping (e.g., with Docker)
• skip: true on a command disables it locally without removing it from the shared config
• New hooks added only in lefthook-local.yml (e.g., post-merge) are merged into the final config

Monorepo Setup

Run different linters for each sub-project in a monorepo by scoping commands with root and glob.

# lefthook.yml

pre-commit:
  parallel: true
  jobs:
    - name: frontend-lint
      root: "frontend/"
      glob: "*.{js,ts,jsx,tsx}"
      run: yarn eslint --fix {staged_files}
      stage_fixed: true
    - name: backend-lint
      root: "backend/"
      glob: "*.rb"
      exclude:
        - "config/initializers/*.rb"
      run: bundle exec rubocop --force-exclusion -- {staged_files}
    - name: proxy-lint
      root: "proxy/"
      glob: "*.go"
      run: golangci-lint run -- {staged_files}

post-checkout:
  piped: true
  commands:
    db-create:
      priority: 1
      run: rails db:create
    db-migrate:
      priority: 2
      run: rails db:migrate

Notes

• root changes the working directory for the command and also filters {staged_files} to only files under that directory
• glob is always evaluated relative to the repository root, not the root directory
• piped: true stops execution on first failure; useful for ordered setup steps like DB migrations
• priority controls execution order within a sequential (non-parallel) hook; 0 (default) means last

Parallel Execution

Run multiple hook commands concurrently to reduce total wait time.

# lefthook.yml

pre-commit:
  parallel: true
  commands:
    lint:
      glob: "*.{js,ts,jsx,tsx}"
      run: yarn eslint {staged_files}
    typecheck:
      run: yarn tsc --noEmit
    test:
      run: yarn vitest related {staged_files}

Notes

• parallel: true at the hook level runs all commands simultaneously
• Use piped: true instead when commands must run sequentially and stop on first failure
• parallel and piped are mutually exclusive — setting both causes an error
• Individual commands within a parallel hook can still use priority to define ordering for non-parallel fallback

samples

Shared Config via Remotes

Fetch hook configuration from a remote Git repository to share a common setup across multiple projects.

# lefthook.yml

remotes:
  - git_url: https://github.com/my-org/lefthook-configs
    configs:
      - shared/pre-commit.yml
      - shared/commit-msg.yml

# Local hooks can still be added alongside remote ones
pre-push:
  commands:
    test:
      run: yarn test

Notes

• Lefthook downloads the remote configs during lefthook install and merges them with the local configuration
• configs lists paths within the remote repository; multiple files can be specified
• Remote configuration is merged before lefthook-local.yml, so local overrides take precedence
• Pin a specific revision with ref to avoid unexpected changes: ref: v1.2.0

cli

Lefthook の CLI コマンド一覧。Git hooks の初期化・実行・管理・検証に使用する。

Git hooks の初期化

lefthook install

lefthook.yml が存在しない場合は空のファイルを作成し、設定されたフックを .git/hooks/ にインストールする。

特定フックのみインストール

lefthook install pre-commit pre-push

Git hooks のアンインストール

lefthook uninstall

警告: .git/hooks/ ディレクトリ内の lefthook が管理するフックをすべて削除する。実行後、lefthook が管理する Git hooks は動作しなくなる。

フックの手動実行

lefthook run <hook-name>

例:

lefthook run pre-commit
lefthook run pre-push

特定ジョブのみ実行

lefthook run pre-commit --job lint --job format

タグを指定して実行

lefthook run pre-commit --tag checks

ステージ済みファイルを全ファイルで上書きして実行

lefthook run pre-commit --all-files

特定ファイルを指定して実行

lefthook run pre-commit --file src/index.ts --file src/app.ts

フックディレクトリの作成付きでフックを追加

lefthook add pre-push --dirs

.git/hooks/pre-push/ ディレクトリを作成する。スクリプトを設定に追加する前に使用することを推奨。

設定のバリデーション

lefthook validate

JSON スキーマを使用して lefthook.yml の正当性をチェックする。

マージ済み設定の表示

lefthook dump

lefthook.yml・リモート設定・lefthook-local.yml 等すべての設定をマージした最終設定を表示する。デバッグに有用。

フックインストール状態の確認

lefthook check-install

フックがインストール済みかつ同期されている場合は終了コード 0、そうでない場合は 1 を返す。

バイナリの自動更新

lefthook self-update

GitHub の最新リリースに更新する。ソースビルドまたは GitHub Releases から直接インストールした場合のみ使用可能。パッケージマネージャー経由でインストールした場合は各パッケージマネージャーの更新コマンドを使用すること。

install

パッケージマネージャー別の Lefthook インストールコマンド。

Node.js (npm)

npm install --save-dev lefthook

Node.js (yarn)

yarn add --dev lefthook

Node.js (pnpm)

pnpm add -D lefthook

pnpm を使う場合は pnpm-workspace.yaml の onlyBuiltDependencies または package.json の pnpm.onlyBuiltDependencies に lefthook を追加し、postinstall が正しく動作するよう設定すること。

Homebrew (macOS / Linux)

brew install lefthook

Ruby (gem)

gem install lefthook

Gemfile 経由でプロジェクトに追加する場合:

bundle add lefthook --group development

Go

go install github.com/evilmartians/lefthook/v2@latest

Go ツール依存としてプロジェクトに追加する場合:

go get -tool github.com/evilmartians/lefthook/v2

Python (pip)

python -m pip install --user lefthook

Python (uv)

uv add --dev lefthook

Python (pipx)

pipx install lefthook

Winget (Windows)

winget install evilmartians.lefthook

Scoop (Windows)

scoop install lefthook

Snap (Linux)

snap install --classic lefthook

Alpine Linux (apk)

sudo apk add --no-cache bash curl
curl -1sLf 'https://dl.cloudsmith.io/public/evilmartians/lefthook/setup.alpine.sh' | sudo -E bash
sudo apk add lefthook

Debian / Ubuntu (apt)

curl -1sLf 'https://dl.cloudsmith.io/public/evilmartians/lefthook/setup.deb.sh' | sudo -E bash
sudo apt install lefthook

CentOS / Fedora (yum)

curl -1sLf 'https://dl.cloudsmith.io/public/evilmartians/lefthook/setup.rpm.sh' | sudo -E bash
sudo yum install lefthook

Mise

mise use lefthook@latest

Devbox

devbox add lefthook@latest

scripts

run-with-env

環境変数を使った Lefthook の動作制御コマンド。

フック実行をスキップして git commit

LEFTHOOK=0 git commit -am "skip hooks"

CI 環境でフックを有効化してインストール

LEFTHOOK=1 npm install
LEFTHOOK=1 yarn install
LEFTHOOK=1 pnpm install

多くの CI システムは CI=true を自動設定し postinstall によるフックインストールを抑制する。LEFTHOOK=1 で強制的にインストールできる。

CI 環境でフックインストールを明示的に抑制

CI=true npm install
CI=true yarn install
CI=true pnpm install

verbose モードで実行

LEFTHOOK_VERBOSE=1 lefthook run pre-commit

フック実行フローの詳細ログを出力する。デバッグに有用。

サマリーのみ出力して実行

LEFTHOOK_OUTPUT=summary lefthook run pre-commit

出力を完全に抑制して実行

LEFTHOOK_OUTPUT=false lefthook run pre-commit

タグ・コマンド名を指定してスキップ

LEFTHOOK_EXCLUDE=ruby,security,lint git commit -am "skip specific checks"

指定したタグまたはコマンド名のフックを一時的にスキップする。

カスタム設定ファイルを指定して実行

LEFTHOOK_CONFIG=~/global_lefthook.yml lefthook run pre-commit

カラー出力を強制有効化

CLICOLOR_FORCE=true lefthook run pre-commit

カラー出力を無効化

NO_COLOR=true lefthook run pre-commit