git-hooks-setup

Git Hooks のセットアップ

Git Hooks をワンコマンドで設定し、チームの開発プロセスを標準化します。

概要

pre-commit／commit-msg／pre-push の hook 設定を自動生成します。コードのフォーマット、コミットメッセージの検証、機密情報のチェックが含まれます。husky とネイティブの Git hooks の 2 つの方法に対応しています。

使用する場面

• ユーザーが Git hooks のセットアップを希望している
• ユーザーが pre-commit またはコミットメッセージの規約について言及している
• ユーザーが lint／フォーマットのチェックを自動化したい
• ユーザーが /git-hooks-setup を入力した
• ユーザーが pre-push チェック（テスト、lint）を適用したい
• ユーザーが壊れたコードのプッシュを防ぎたい
• ユーザーがチームのコミットメッセージ形式を標準化したい
• ユーザーがコミット前にシークレットスキャンを追加したい
• ユーザーがコミットのたびにコードを自動フォーマットしたい

使用しない場面：

• ユーザーが現在の Git hooks の設定を確認したいだけの場合
• ユーザーが CI ベースのチェックを希望している場合（ローカル hooks は不要）
• プロジェクトにすでに完全な hooks のセットアップがある場合
• ユーザーが特定のファイルだけで hooks を実行したい場合（lint-staged を直接使用してください）
• ユーザーが pre-commit／commit-msg／push 以外の Git イベントに hook を設定したい場合

基本的な手順

Step 1: プロジェクト環境を検出する

# 检测包管理器（按 lock 文件判断）
if [ -f "package-lock.json" ]; then PACKAGE_MANAGER="npm"
elif [ -f "yarn.lock" ]; then PACKAGE_MANAGER="yarn"
elif [ -f "pnpm-lock.yaml" ]; then PACKAGE_MANAGER="pnpm"

# 检测已有 hooks 配置
test -d ".husky" && echo "husky 已配置"
test -f ".git/hooks/pre-commit" && echo "原生 hooks 已配置"

# 从 package.json 检测已安装的 lint 工具（eslint/prettier/lint 相关）

Step 2: 方法を選択する

方法	適用シーン	メリット
husky	Node.js プロジェクト	チームでの共同作業に適しており、設定をコードとして管理
ネイティブ Git hooks	Node.js 以外のプロジェクト	依存関係なし

Step 3: 設定を生成する

方法 A: Husky

# 根据 $PACKAGE_MANAGER 选择: pnpm dlx / yarn dlx / npx
husky init    # 初始化 husky

.husky/pre-commit（lint-staged を実行）と .husky/commit-msg（commitlint を実行）を生成します。対話型インストールを避けるため、commitlint には --no プレフィックスを付けてください。

lint-staged の設定を生成します（package.json に書き込みます）。

{
  "lint-staged": {
    "*.{ts,tsx,js,jsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md,yml}": ["prettier --write"]
  }
}

.husky/pre-push を生成します（任意。push 前にテストを実行します）。

# 根据包管理器选择命令
if [ "$PACKAGE_MANAGER" = "pnpm" ]; then
  pnpm test
elif [ "$PACKAGE_MANAGER" = "yarn" ]; then
  yarn test
else
  npm test
fi

方法 B: ネイティブ Git hooks

cat > .git/hooks/pre-commit << 'EOF'
#!/bin/sh
# 自动 lint + format（按项目实际替换命令；示例为 Node 项目）
if [ -f "package.json" ] && [ -x "$(command -v npm)" ]; then
  npm run lint -- --fix 2>/dev/null || true
  npm run format 2>/dev/null || true
fi
# 注意：不要执行 git add -u —— 那会把用户未暂存的改动也一并提交。
# 若需把 lint 修复的结果纳入提交，请使用 lint-staged（只处理暂存文件）。
EOF
chmod +x .git/hooks/pre-commit

# pre-push hook（可选，push 前跑测试；按项目实际替换）
cat > .git/hooks/pre-push << 'EOF'
#!/bin/sh
if [ -f "package.json" ] && [ -x "$(command -v npm)" ]; then
  npm test || exit 1
fi
EOF
chmod +x .git/hooks/pre-push

Step 4: コミットメッセージの規約を設定する

templates/commitlint.config.js をプロジェクトのルートディレクトリにコピーします（commitlint.config.js）。この設定は @commitlint/config-conventional に基づいており、コミットメッセージの形式を検証します。

type(scope): subject

# type: feat|fix|docs|style|refactor|test|chore|perf|ci|build|revert
# scope: 可选，影响范围
# subject: 简短描述（header-max-length 限制 100 字符）

commitlint の依存関係もインストールします。

npm install -D @commitlint/cli @commitlint/config-conventional

Step 5: 機密情報のチェックを追加する

⚠️ grep "password|secret|token" のようなキーワードスキャンは使わないでください。業務コードに「token」や「secret」という文字列が含まれるのは一般的であり、大量の誤検出によりコミットが頻繁にブロックされます。

gitleaks の使用を推奨します（シークレットスキャン専用ツールで、エントロピー検出と許可リストを内蔵し、誤検出率が低いです）。

# 生成 gitleaks pre-commit hook
npx gitleaks git-config 2>/dev/null || brew install gitleaks && gitleaks git-config
# 或手动在 .git/hooks/pre-commit 中加入：
# gitleaks protect --staged --verbose 2>&1
# 若 gitleaks 不可用，宁可跳过也不要退化成关键字 grep

どうしても gitleaks をインストールできない場合は、次善策として単語全体の誤検出も避けてください。信頼度の高いパターン（秘密鍵のブロックや AWS キーの形式など）のみを照合し、業務でよく使われる token／secret／password などの単語は照合しないでください。

# 低误报替代方案：只扫私钥和云厂商密钥格式（示例）
if git diff --cached --diff-filter=ACM --name-only -z | xargs -0 grep -IlE "BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY|AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{36}" 2>/dev/null | grep -q .; then
  echo "警告: 检测到可能的密钥泄露，请检查后重新提交"
  exit 1
fi

クイックリファレンス

/git-hooks-setup                    # 交互式选择方案和 hooks
/git-hooks-setup --husky            # 直接用 husky
/git-hooks-setup --native           # 直接用原生 git hooks

パラメーター	説明	デフォルト値
--husky	husky を使用	自動検出
--native	ネイティブ Git hooks を使用	false
--commitlint	コミットメッセージの検証を追加	true

よくある間違い

間違い	正しい方法	理由
hook スクリプトに実行権限がない	chmod +x .git/hooks/*	hook が実行されません
lint-staged のルールを増やしすぎる	ステージング済みファイルのみをチェックする	コミットの待ち時間を短縮できます
コミットメッセージの検証が厳しすぎる	最初は緩く設定し、徐々に厳しくする	チームの反発を避けられます
機密情報をチェックしない	シークレットスキャンを追加する	情報漏えいを防止できます
.git/hooks をコミットしない	husky／lefthook で管理する	チームで設定を共有する必要があります
pre-push hook の実行に時間がかかりすぎる	高速なチェックのみを実行し、完全なテストは CI で実施する	push がブロックされると効率に影響します
hook で相対パスを使用する	絶対パスまたはプロジェクトのルートディレクトリを使用する	実行するディレクトリによってパスの解決に失敗します
prepare スクリプトをスキップする	package.json の prepare で husky を実行する（v9+）	CI 環境で hook が機能しません
commitlint のルールがチームの規約と一致しない	commitlint.config.js で一元管理する	口頭での取り決めは守られないことがあります
--no-verify の許可リストを設定しない	--no-verify を許可し、ログを記録する	緊急修正が完全にブロックされるのを防げます