Git hooks・husky v9の設定方法｜実行結果とlefthook比較

Git hooksとは、git commit や git push などの操作の前後にGitが自動で実行するスクリプトのことで、huskyはそのスクリプトをリポジトリ内の .husky/ フォルダで管理し、npm install した全員に同じフックを配る仕組みです。フックを使うと、「lintを通していないコードをコミットできない」「規約に合わないコミットメッセージを受け付けない」「テストが落ちる状態ではpushできない」といったルールを、チーム全員の手元で自動的に守れます。

この記事では、まずGit hooks 8種の早見表（タイミング・引数・止められるか）を示し、素の .git/hooks と core.hooksPath で最小例を動かしてから、husky 9.1.7 の現行手順（npx husky init）を、lint-staged 17.6.0・commitlint 21.2.3・pre-push でのテストと組み合わせて実際に実行します。コミットが止まる出力と通る出力を両方そのまま掲載し、--no-verify や HUSKY=0・CI・モノレポでの扱い、lefthook 2.1.15 と pre-commit 4.6.2（pip）との比較表、フックが動かない時の対処表まで、検索上位の記事にはない実測ベースでまとめました。バージョンはすべてnpm・PyPIで2026年10月1日に確認したものです。

Git hooksの早見表

まずは「どのフックが・いつ・何を受け取って・止められるか」の一覧です。コミットを止めたいなら pre-commit か commit-msg、pushを止めたいなら pre-push と覚えておくと、ほとんどの用途は足ります。

補足として、Git公式ドキュメント（githooks）に書かれている前提を3つ押さえておきます。

• フックは $GIT_DIR/hooks/（通常は .git/hooks/）にある実行可能ファイルが対象で、git config core.hooksPath で場所を変えられます（Git 2.9以降）
• .git/hooks/ は git clone でコピーされません。チームで共有するには、リポジトリ内のフォルダを core.hooksPath に向けるか、husky・lefthook・pre-commit のようなツールで各自の環境にインストールする必要があります
• クライアント側のフックはワーキングツリーのルートをカレントディレクトリとして実行されます

素のGit hooksで最小例を動かす

ツールを入れる前に、Gitが素で持っている仕組みを2通り（.git/hooks/ 直置きと core.hooksPath）で動かしておくと、huskyが内部で何をしているかがよくわかります。検証環境は git 2.43.0（Linux）です。

.git/hooks/pre-commit にスクリプトを置く

git init 直後の .git/hooks/ には pre-commit.sample など14個のサンプルがあり、.sample を外した名前の実行可能ファイルを置くだけでフックは有効になります。ステージ済みの .js に console.log が残っていたらコミットを止める最小例です。

#!/bin/sh
# .git/hooks/pre-commit
# ステージ済みの .js ファイルに console.log が残っていたらコミットを止める
files=$(git diff --cached --name-only --diff-filter=ACMR -- '*.js')
[ -z "$files" ] && exit 0
if grep -Hn 'console\.log' $files; then
  echo "pre-commit: console.log が残っています。削除してからコミットしてください。"
  exit 1
fi

chmod +x .git/hooks/pre-commit
git add util.js
git commit -m "add label()"

実行結果（止まる場合）です。フックが非ゼロで終了すると、Gitは何も言わずにコミットを中止します。メッセージはフック自身が出したものです。

util.js:2:  console.log("label", n);
pre-commit: console.log が残っています。削除してからコミットしてください。
exit code: 1

console.log を消して再度コミットすると、そのまま通ります。

[main 9e8d2fe] add label()
 1 file changed, 3 insertions(+)
 create mode 100644 util.js
exit code: 0

実行権限が付いていないと、フックは無視されます。この場合Gitがヒントを出してくれるので、「フックが動かない」と感じたらまずこの行を探します（chmod -x で再現）。

hint: The '.git/hooks/pre-commit' hook was ignored because it's not set as executable.
hint: You can disable this warning with `git config advice.ignoredHook false`.
[main fba1c37] add label()

core.hooksPath でリポジトリ内のフォルダを使う

.git/hooks/ はcloneで配られないため、フックをリポジトリ内の .githooks/ に置いてコミットし、各自が git config core.hooksPath .githooks を1回実行するのが、ツールなしで共有する定番です。commit-msg と prepare-commit-msg を置いて、引数の中身も確認します。

#!/bin/sh
# .githooks/commit-msg  （$1 = コミットメッセージが入った一時ファイル）
msg=$(head -n1 "$1")
if ! echo "$msg" | grep -Eq '^(feat|fix|docs|refactor|test|chore)(\(.+\))?: .+'; then
  echo "commit-msg: 1行目は 'feat: 内容' の形式にしてください。受け取った1行目: $msg"
  exit 1
fi

#!/bin/sh
# .githooks/prepare-commit-msg  （$1=メッセージファイル, $2=由来, $3=コミットID）
echo "prepare-commit-msg: \$1=$1 \$2=$2 \$3=$3"

chmod +x .githooks/*
git config core.hooksPath .githooks
git add version.js .githooks
git commit -m "version file"

prepare-commit-msg: $1=.git/COMMIT_EDITMSG $2=message $3=
commit-msg: 1行目は 'feat: 内容' の形式にしてください。受け取った1行目: version file
exit code: 1

-m で渡したので $2 は message、amendではないので $3 は空です。feat: を付けると通ります。

prepare-commit-msg: $1=.git/COMMIT_EDITMSG $2=message $3=
[main 3b37873] feat: add version file
 3 files changed, 11 insertions(+)
 create mode 100755 .githooks/commit-msg
 create mode 100755 .githooks/prepare-commit-msg
 create mode 100644 version.js
exit code: 0

core.hooksPath を設定すると .git/hooks/ は見られなくなる点と、設定はリポジトリごと（.git/config）なのでcloneした人が各自実行する必要がある点が、この方式の運用上のポイントです。husky v9は、まさにこの core.hooksPath を npm install 時に自動設定するツールです。

husky v9の設定方法（npx husky init）

インストールと初期化

前提はNode.js 18以上（検証は Node 22.22.2 / npm 10.9.7 / husky 9.1.7）。v9では npx husky init の1コマンドで初期設定が完了します。

npm i -D husky
npx husky init

husky init が行うのは次の3つです。

実行後の状態です。

{
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "prepare": "husky"
  },
  "devDependencies": {
    "husky": "^9.1.7"
  }
}

$ cat .husky/pre-commit
npm test

$ git config core.hooksPath
.husky/_

$ ls .husky/_
.gitignore  applypatch-msg  commit-msg  h  husky.sh  post-applypatch  post-checkout
post-commit  post-merge  post-rewrite  pre-applypatch  pre-auto-gc  pre-commit
pre-merge-commit  pre-push  pre-rebase  prepare-commit-msg

.husky/_/ の各フックはすべて同じ2行で、h というスクリプトが「同名のファイル .husky/<フック名> があれば sh -e で実行する」だけの仕組みです。.husky/_/ は .gitignore（中身は *）で無視され、コミットされるのは .husky/pre-commit などの中身だけです。

#!/usr/bin/env sh
. "$(dirname "$0")/h"

h の中身（9.1.7）を読むと、この記事で後述する挙動がすべて説明できます（右側のコメントは筆者が追加したものです）。

#!/usr/bin/env sh
[ "$HUSKY" = "2" ] && set -x                      # HUSKY=2 でデバッグ出力
n=$(basename "$0")
s=$(dirname "$(dirname "$0")")/$n                  # .husky/<フック名>

[ ! -f "$s" ] && exit 0                            # ファイルがなければ何もしない

if [ -f "$HOME/.huskyrc" ]; then
    echo "husky - '~/.huskyrc' is DEPRECATED, please move your code to ~/.config/husky/init.sh"
fi
i="${XDG_CONFIG_HOME:-$HOME/.config}/husky/init.sh"
[ -f "$i" ] && . "$i"                              # 個人用の初期化ファイルを読む

[ "${HUSKY-}" = "0" ] && exit 0                    # HUSKY=0 でスキップ

export PATH="node_modules/.bin:$PATH"              # npx なしでもコマンドが見つかる
sh -e "$s" "$@"                                    # -e: 途中で失敗したら即終了
c=$?

[ $c != 0 ] && echo "husky - $n script failed (code $c)"
[ $c = 127 ] && echo "husky - command not found in PATH=$PATH"
exit $c

最初のコミットで動作確認

npm test が「テスト未設定」で exit 1 するので、初期状態ではコミットが止まります。これが動作確認になります。

$ git add -A && git commit -m "chore: add husky"

> husky-demo@1.0.0 test
> echo "Error: no test specified" && exit 1

Error: no test specified
husky - pre-commit script failed (code 1)
exit code: 1

HUSKY=0 を付けるとフックを飛ばしてコミットできます（初回だけこの方法で入れると、履歴がきれいになります）。

$ HUSKY=0 git commit -m "chore: add husky"
[main 11c3157] chore: add husky
 3 files changed, 39 insertions(+), 2 deletions(-)
 create mode 100644 .husky/pre-commit
 create mode 100644 package-lock.json

v8以前の手順との違い

検索上位にはv6〜v8時代の手順が多く残っています。v9で削除・非推奨になったコマンドを打つと、9.1.7では次のメッセージが出ます。

pre-commitでlint-stagedを動かす

lint-stagedは、ステージされたファイルだけを対象にlintやフォーマッタを走らせるツールです。プロジェクト全体にESLintをかけると数十秒かかる場合でも、変更した数ファイルなら1〜2秒で終わります。lint-staged 17.6.0 は Node 22.22.1 以上が必要です。

npm i -D lint-staged eslint @eslint/js prettier   # lint-staged 17.6.0 / eslint 10.11.0 / prettier 3.9.9
echo "npx lint-staged" > .husky/pre-commit

.lintstagedrc.json（キーがglob、値が実行コマンド。配列なら順に実行）と、no-unused-vars と no-console をエラーにした eslint.config.js です。

{
  "*.js": ["eslint --fix", "prettier --write"],
  "*.{json,md,yml}": "prettier --write"
}

// eslint.config.js（package.json に "type": "module" がある前提）
import js from "@eslint/js";

export default [
  js.configs.recommended,
  {
    files: ["**/*.js"],
    languageOptions: {
      ecmaVersion: 2024,
      sourceType: "module",
      globals: { console: "readonly" },
    },
    rules: {
      "no-unused-vars": "error",
      "no-console": "error",
    },
  },
];

コミットが止まる出力

未使用変数と console.log を含む src.js をコミットしてみます。

export function total(items) {
  const unused = 1;
  console.log(items);
  return items.reduce((sum, i) => sum + i.price * i.qty, 0);
}

$ git add src.js && git commit -m "feat: add total()"
⋯ Backing up original state…
✔ Done backing up original state (aaf8e48)!
⋯ Running tasks for staged files…
    *.js — 1 file
      ⋯ eslint --fix
      ⋯ prettier --write

✖ eslint --fix
↓ prettier --write

✖ Failed to run tasks for staged files!
↓ Skipped staging changes from tasks…
⋯ Reverting to original state because of errors…
✔ Done reverting to original state!
⋯ Cleaning up temporary files…
✔ Done cleaning up temporary files!

✖ eslint --fix:

/path/to/husky-demo/src.js
  2:9  error  'unused' is assigned a value but never used  no-unused-vars
  3:3  error  Unexpected console statement                 no-console

✖ 2 problems (2 errors, 0 warnings)
husky - pre-commit script failed (code 1)
exit code: 1

出力の読み方は次のとおりです（パスは短縮しています）。

• Backing up original state：lint-stagedは実行前に作業ツリーの状態を退避し、失敗したら Reverting to original state で元に戻します。--fix が途中まで書き換えた状態が残る心配はありません
• ✖ eslint --fix で止まった後の ↓ prettier --write は「実行されなかった」印です
• 最後の husky - pre-commit script failed (code 1) はhuskyの h が付けた行で、どのフックが何番で失敗したかがわかります

コミットが通る出力（自動整形がステージされる）

エラーを直し、わざとインデントを4つ・セミコロンなしにした状態でコミットすると、prettierが整形した結果が自動でステージに反映されてコミットされます。

$ git add src.js && git commit -m "feat: add total()"
⋯ Backing up original state…
✔ Done backing up original state (f21931a)!
⋯ Running tasks for staged files…
    *.js — 1 file
      ⋯ eslint --fix
      ⋯ prettier --write

✔ eslint --fix
✔ prettier --write

✔ Done running tasks for staged files!
⋯ Staging changes from tasks…
✔ Done staging changes from tasks!
⋯ Cleaning up temporary files…
✔ Done cleaning up temporary files!
[main ab12ad3] feat: add total()
 1 file changed, 3 insertions(+)
 create mode 100644 src.js
exit code: 0

$ git show HEAD:src.js
export function total(items) {
  return items.reduce((sum, i) => sum + i.price * i.qty, 0);
}

lint-stagedの設定でつまずきやすい点

.husky/pre-commit に npx lint-staged と書きましたが、h が node_modules/.bin を PATH に足すので lint-staged だけでも動きます。npx を付けておくと、フック以外から手で実行した時も同じ書き方で済みます。

commit-msgでcommitlintを動かす

commitlintは、コミットメッセージが「type(scope): subject」形式（Conventional Commits）に沿っているかを検査するツールです。commit-msg フックは $1 にメッセージファイルのパスを受け取るので、それを --edit に渡します。

npm i -D @commitlint/cli @commitlint/config-conventional   # 21.2.3
echo 'npx --no -- commitlint --edit "$1"' > .husky/commit-msg

// commitlint.config.js（"type": "module" の場合。CJSなら module.exports = {...}）
export default { extends: ["@commitlint/config-conventional"] };

npx --no は「未インストールならレジストリから取りに行かずに失敗する」指定で、フックの中でネットワークアクセスが発生しないようにするためのものです。

止まるメッセージと通るメッセージ

$ git commit -m "update tax"
⧗   --- input ---
update tax
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

✖   found 2 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

husky - commit-msg script failed (code 1)
exit code: 1

$ git commit -m "Feat: Add tax rate."
⧗   --- input ---
Feat: Add tax rate.
✖   subject must not be sentence-case [subject-case]
✖   subject may not end with full stop [subject-full-stop]
✖   type must be lower-case [type-case]
✖   type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test] [type-enum]

✖   found 4 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

husky - commit-msg script failed (code 1)
exit code: 1

$ git commit -m "feat(order): add tax rate"
[main b26b527] feat(order): add tax rate
 1 file changed, 1 insertion(+)
 create mode 100644 tax.js
exit code: 0

[type-enum] のようにルール名が角かっこで出るので、緩めたい時は commitlint.config.js の rules にそのルール名で上書きします（例："subject-case": [0] で無効化）。メッセージの書き方自体の規約は、コミットメッセージの記事に譲ります。

pre-pushでテストを動かす

pushの直前にテストを走らせると、落ちるコードがリモートに上がることを手元で止められます。pre-push はコミットのたびには走らないので、数十秒かかるテストでも置きやすいフックです。例では外部ライブラリ不要の node --test を使います。

npm pkg set scripts.test="node --test --test-reporter=spec"
echo "npm test" > .husky/pre-push

// src.test.js
import { test } from "node:test";
import assert from "node:assert/strict";
import { total } from "./src.js";

test("total() sums price * qty", () => {
  assert.equal(total([{ price: 100, qty: 2 }, { price: 50, qty: 1 }]), 240);
});

期待値をわざと間違えた（正しくは250）状態でpushすると止まります（スタックトレースは一部省略）。

$ git push -u origin main

> husky-demo@1.0.0 test
> node --test --test-reporter=spec

✖ total() sums price * qty (1.17386ms)
ℹ tests 1
ℹ pass 0
ℹ fail 1

✖ failing tests:

test at src.test.js:5:1
✖ total() sums price * qty (1.17386ms)
  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:

  250 !== 240

      at TestContext.<anonymous> (/path/to/husky-demo/src.test.js:6:10)
husky - pre-push script failed (code 1)
error: failed to push some refs to '../remote.git'
exit code: 1

error: failed to push some refs to は、フックが非ゼロで終わった時にGitが出す定型文です。テストを直すと通ります（ℹ の集計行は一部省略）。

$ git push

> husky-demo@1.0.0 test
> node --test --test-reporter=spec

✔ total() sums price * qty (0.793033ms)
ℹ tests 1
ℹ pass 1
ℹ fail 0
To ../remote.git
   edd4bd0..b6622ad  main -> main
exit code: 0

ここまでの .husky/ の完成形は次の3ファイルです。

.husky/pre-commit   → npx lint-staged
.husky/commit-msg   → npx --no -- commitlint --edit "$1"
.husky/pre-push     → npm test

フックをスキップする方法とCI・モノレポでの設定

スキップの方法の早見表

実行例です。--no-verify を付けると、lintに通らないファイルも規約外のメッセージもそのまま入ります。

$ git add bad.js && git commit -m "wip" --no-verify
[main 1dbabeb] wip
 1 file changed, 2 insertions(+)
 create mode 100644 bad.js
exit code: 0

CI（GitHub Actions）ではフックを入れない

CIではコミットしないのでフックは不要です。husky公式が案内するのは環境変数 HUSKY: 0 の設定で、prepare が走っても husky は HUSKY=0 skip install と表示して何もしません。

# .github/workflows/ci.yml
name: ci
on: [push, pull_request]
env:
  HUSKY: 0
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm test

npm ci の付け方によって prepare の挙動が変わるので、cloneしたての状態で試した結果を表にします。--omit=dev は「devDependenciesのhuskyがないのに prepare は走る」ため失敗するのが最も多いつまずきです。

本番イメージのビルドなど --omit=dev を使う場面では、HUSKY=0 を渡すか、"prepare": "husky || true" にしておくと安全です。もう少し丁寧にするなら、公式の例のように .husky/install.mjs で CI や NODE_ENV=production の時に process.exit(0) する方法もあります。

モノレポ（package.jsonがサブディレクトリにある場合）

huskyはカレントディレクトリに .git があることを前提にしているので、frontend/ の中で npx husky を実行すると次のように出ます。

$ cd frontend && npx husky
.git can't be found

公式の対処は、prepare でリポジトリのルートに移動してから .husky の場所を引数で渡す方法です。フック側では逆に frontend/ に降りてから実行します。

{
  "scripts": {
    "prepare": "cd .. && husky frontend/.husky"
  }
}

# frontend/.husky/pre-commit
cd frontend
npx lint-staged

$ npm run prepare
> frontend@1.0.0 prepare
> cd .. && husky frontend/.husky

$ git config core.hooksPath
frontend/.husky/_

$ git commit -m "chore: husky in subdir"
> frontend@1.0.0 test
> echo frontend-test-ok
frontend-test-ok
[main (root-commit) 3604463] chore: husky in subdir

lint-staged側は、各パッケージに .lintstagedrc.json を置くと、ステージされたファイルに最も近い設定ファイルが使われ、その設定のディレクトリでコマンドが実行されるので、パッケージごとに違うlint設定でも1つの pre-commit から扱えます。

lefthook・pre-commit（pip）との比較

huskyはNode.jsプロジェクトの定番ですが、Go製の lefthook（並列実行・言語非依存）と Python製の pre-commit（Pythonプロジェクトの定番）も広く使われています。同じ「ESLint + Prettier + commitlint」を lefthook で、「ruff」を pre-commit で動かして比べます。

lefthook 2.1.15 の最小設定

npmからは npm i -D lefthook で入り、postinstallで lefthook install が自動実行されます（バイナリはプラットフォーム別パッケージ lefthook-linux-x64 などから取得）。設定は lefthook.yml 1ファイルで、フック名の下に jobs を並べ、parallel: true で並列実行できます。

# lefthook.yml（lefthook 2.1.15）
pre-commit:
  parallel: true
  jobs:
    - name: eslint
      glob: "*.js"
      run: npx eslint --fix {staged_files}
      stage_fixed: true
    - name: prettier
      glob: "*.{js,json,md,yml}"
      run: npx prettier --write {staged_files}
      stage_fixed: true

commit-msg:
  jobs:
    - name: commitlint
      run: npx --no -- commitlint --edit {1}

pre-push:
  jobs:
    - name: test
      run: npm test

{staged_files} がステージ済みファイル、{1} がフックの第1引数、stage_fixed: true が「修正結果を自動でステージ」に相当します。lefthook.yml を書き換えたら npx lefthook install で同期します。

$ npx lefthook install
sync hooks: ✔️(pre-commit, commit-msg, pre-push)

huskyと違ってcore.hooksPath は変えず、.git/hooks/pre-commit などに「lefthookを探して lefthook run pre-commit を呼ぶ」ラッパーを書き込みます。同じ src.js をコミットした出力です（色コードは除去）。

$ git commit -m "add total"
╭───────────────────────────────────────╮
│ lefthook  v2.1.15   hook:  pre-commit │
╰───────────────────────────────────────╯
┃  prettier ❯
src.js 70ms (unchanged)

┃  eslint ❯

/path/to/lefthook-demo/src.js
  2:9  error  'unused' is assigned a value but never used  no-unused-vars
  3:3  error  Unexpected console statement                 no-console

✖ 2 problems (2 errors, 0 warnings)

exit status 1
  ────────────────────────────────────
summary: (done in 2.00 seconds)
✓ prettier (1.70 seconds)
✗ eslint (1.99 seconds)
exit code: 1

コードを直してメッセージが規約外のままだと、pre-commit は通り commit-msg で止まります。

$ git commit -m "add total"
（pre-commit の枠は省略：✓ prettier ✓ eslint）
╭───────────────────────────────────────╮
│ lefthook  v2.1.15   hook:  commit-msg │
╰───────────────────────────────────────╯
┃  commitlint ❯
⧗   --- input ---
add total
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

✖   found 2 problems, 0 warnings

exit status 1
summary: (done in 0.81 seconds)
✗ commitlint (0.81 seconds)
exit code: 1

$ git commit -m "feat: add total()"
（pre-commit・commit-msg とも ✓）
[main cb92b7f] feat: add total()
 1 file changed, 3 insertions(+)
 create mode 100644 src.js
exit code: 0

スキップは LEFTHOOK=0 git commit ...、手動実行は npx lefthook run pre-commit --all-files、有効な設定の確認は npx lefthook dump です。

pre-commit 4.6.2（pip）の最小設定

pre-commit（ツール名がフック名と同じなので紛らわしいのですが）は、.pre-commit-config.yaml に「どのリポジトリの・どのバージョンの・どのフックを使うか」を書き、ツールが各フックの実行環境を自動で用意する仕組みです。Pythonプロジェクトの定番で、pre-commit sample-config がひな形を出してくれます。

pip install pre-commit        # 4.6.2
pre-commit sample-config > .pre-commit-config.yaml
pre-commit install            # .git/hooks/pre-commit に書き込む
pre-commit run --all-files    # 手動で全ファイルに実行
pre-commit autoupdate         # rev を最新タグに更新

一般的な設定は次のように公開リポジトリを指定します（この環境からはGitHubに接続できないため、この形は未実行です）。

# .pre-commit-config.yaml（一般的な形。rev は pre-commit autoupdate で更新）
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v6.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.16.8
    hooks:
      - id: ruff-check
        args: [--fix]
      - id: ruff-format

同じ内容を、手元にインストール済みのコマンドを呼ぶ repo: local で書いて実行しました。

# .pre-commit-config.yaml（repo: local 版。pre-commit 4.6.2 / ruff 0.16.9 で実行）
repos:
  - repo: local
    hooks:
      - id: ruff-check
        name: ruff check
        entry: ruff check --fix
        language: system
        types: [python]
      - id: ruff-format
        name: ruff format
        entry: ruff format
        language: system
        types: [python]

$ pre-commit install
pre-commit installed at .git/hooks/pre-commit

$ git add -A && git commit -m "add total()"
ruff check...............................................................Failed
- hook id: ruff-check
- exit code: 1
- files were modified by this hook

F841 Local variable `unused` is assigned to but never used
 --> app.py:3:5
  |
2 | def total(items):
3 |     unused = 1
  |     ^^^^^^
4 |     return sum(i["price"] * i["qty"] for i in items)
  |
help: Remove assignment to unused variable `unused`

Found 2 errors (1 fixed, 1 remaining).
No fixes available (1 hidden fix can be enabled with the `--unsafe-fixes` option).

ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted

exit code: 1

pre-commitは「フックがファイルを書き換えたら、それだけで Failed 扱い」です（files were modified by this hook）。未使用importの削除と整形は自動で済んでいるので、残った unused = 1 を消して git add し直せば通ります。

$ git add -A && git commit -m "add total()"
ruff check...............................................................Passed
ruff format..............................................................Passed
[main (root-commit) 75fbda2] add total()
 3 files changed, 17 insertions(+)

特定フックだけ飛ばすには SKIP=ruff-check git commit ...、全部飛ばすなら git commit --no-verify です。

4方式の比較表

どれを選ぶかの判断表

よくあるトラブルと対処表

以下はすべてこの記事の検証中に実際に再現した出力です。

~/.config/husky/init.sh は、GUIクライアント対策の要です。nvmなら次の2行を置きます。

# ~/.config/husky/init.sh
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

よくある質問

Q. .husky/_ はコミットすべきですか？ A. しません。husky が生成する .husky/_/.gitignore（中身は *）で自動的に無視されます。コミットするのは .husky/pre-commit など自分で書いたファイルだけで、cloneした人は npm install の prepare で .husky/_ が再生成されます。

Q. npx husky init で作られた pre-commit の npm test は消していいですか？ A. 構いません。npm test は「フックが動くことを確かめる」ためのサンプルで、実運用では npx lint-staged などに書き換えます。テストは pre-push に置くと、コミットのたびに待たされずに済みます。

Q. yarn や pnpm でも手順は同じですか？ A. pnpm は pnpm add -D husky && pnpm exec husky init、bun は bun add --dev husky && bunx husky init で同じです。Yarn 2以降は prepare を自動実行しないため、公式ドキュメントでは postinstall に husky を書き、公開パッケージなら pinst で npm publish 時の実行を抑える方法が案内されています。

Q. フックを一時的に全部止めたいときは？ A. 1回なら HUSKY=0 git commit ...、しばらく止めるなら export HUSKY=0（戻すときは unset HUSKY）です。git commit --no-verify は pre-commit と commit-msg だけを飛ばし、prepare-commit-msg は飛ばせない点が違います。

まとめ

• Git hooksは .git/hooks/ の実行可能ファイル。pre-commit・commit-msg・pre-push は非ゼロ終了で操作を止められ、post-* は止められない（早見表参照）
• .git/hooks/ はcloneで配られないので、共有には core.hooksPath かツールが必要。husky v9は npm install の prepare で core.hooksPath=.husky/_ を自動設定する
• husky v9の手順は npm i -D husky && npx husky init の2行。husky install / husky add は非推奨で、フックは .husky/<フック名> にコマンドを直接書く
• lint-stagedは失敗時に元の状態へ自動で戻し、成功時は整形結果を自動ステージする。tsc は関数形式でファイル名を捨てる
• commit-msg は npx --no -- commitlint --edit "$1"、pre-push は npm test。止まる時は husky - <フック名> script failed (code N) が出る
• CIでは HUSKY: 0。npm ci --omit=dev は husky: not found で失敗するので HUSKY=0 か "prepare": "husky || true" にする
• 複数言語のモノレポはlefthook、Pythonはpre-commitが向く。フックが動かない時は実行権限・core.hooksPath・CRLF・PATH の4点を順に確認する

株式会社RJCでは、Git hooksのようにチームの品質を自動で支える仕組みを、プロジェクトの中で仲間と学び合っています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。