Git Pre-commit Hook によるコード検証の自動化

コードを書いて git commit し、リモートリポジトリにプッシュした直後、カンマの押し忘れやフォーマットエラーで CI/CD ビルドが失敗した経験はありませんか？

このような問題は Git Pre-commit Hook を活用することで、コミット前にローカル環境で防止できます。

Git Pre-commit Hook とは#

Git Hooks は、Git ワークフローの特定のイベント（コミット前、プッシュ前など）でスクリプトを自動実行する機能です。

その中でも pre-commit フック は git commit コマンドが実行された直後、コミットオブジェクトが作成される前に動作します。スクリプトの終了コードが 0 以外の場合、コミット処理は即座に中断されます。

graph LR
    A[git commit 実行] --> B{Pre-commit Hook}
    B -->|終了コード = 0| C[コミット成功]
    B -->|終了コード != 0| D[コミット中断 & エラー表示]

フック共有の課題と core.hooksPath#

デフォルトの Git フックは .git/hooks/ ディレクトリ内に配置されますが、.git ディレクトリは バージョン管理対象外 です。そのため以下の課題が生じます：

1. チーム間での共有が困難: 各開発者が手動で .git/hooks/ にスクリプトをコピーする必要がある。
2. 設定忘れ: 新しいメンバーが加入した際に設定手順を失念しやすい。

core.hooksPath による解決策#

Git 2.9 以降では、core.hooksPath 設定によりフックの参照先ディレクトリを任意に変更できます。

リポジトリ直下の .githooks/ フォルダでフックを管理し、以下のように設定します：

git config core.hooksPath .githooks

Node.js や Bun プロジェクトでは package.json の prepare スクリプトに登録することで自動化できます：

{
  "scripts": {
    "prepare": "git config core.hooksPath .githooks"
  }
}

これで npm install や bun install の実行時に自動で .githooks が適用されます。

実践例: agent-md による Markdown 自動整形#

以下は、agent-md CLI が存在する場合にステージングされた Markdown ファイルを自動フォーマットする pre-commit フックの実装例です。

#!/usr/bin/env bash

# 1. agent-md CLI が利用可能かチェック
if command -v agent-md >/dev/null 2>&1; then
  # 2. ステージングされた Markdown ファイルを取得（削除ファイル除く）
  STAGED_MD_FILES=$(git diff --cached --name-only --diff-filter=d | grep -E '\.(md|mdx)$')
  
  if [ -n "$STAGED_MD_FILES" ]; then
    echo "[git-hook] agent-md で Markdown ファイルを自動整形中..."
    for file in $STAGED_MD_FILES; do
      if [ -f "$file" ]; then
        agent-md "$file"
        git add "$file"
      fi
    done
  fi
fi

実行権限の付与を忘れずに行ってください：

chmod +x .githooks/pre-commit

Pre-commit フックのスキップ方法#

作業途中のコードを緊急で退避させたい場合などは、--no-verify (または -n) フラグを付けることでフックを一時的にスキップできます：

git commit -m "WIP: 一時保存" --no-verify

[!TIP] リポジトリ内のコード品質を保つため、--no-verify の使用は最小限にとどめましょう。

参考文献#

• Git Customizing Git - Git Hooks ↗
• Git Config core.hooksPath Documentation ↗