commitlintとcommitizenで整えるコミットメッセージ運用
概要
コミットメッセージは「あとで読む誰か」のためのドキュメントです。しかし個人の裁量に任せると、fix・修正・とりあえず のような履歴が溜まり、git log から変更の意図が読み取れなくなります。
本記事では Conventional Commits を規約として採用し、
commitlintでメッセージ形式を機械的に検証しhuskyでコミット時に自動でチェックを走らせcommitizenで対話的に正しい形式のメッセージを作成する
という3点セットを、手を動かしながら構築します。ゴールは「規約を知らないメンバーでも、質問に答えるだけで規約準拠のコミットが打てる」状態です。
環境
本記事は以下を前提とします。
- Node.js 20.x / npm 10.x
- Git 2.40 以上
@commitlint/cliv19 系 /huskyv9 系 /commitizenv4 系 /cz-conventional-changelogv3 系
発生していた問題
規約がないプロジェクトの git log --oneline は、だいたいこうなります。
a1b2c3d fix e4f5g6h 修正 i7j8k9l WIP m0n1o2p ちょっと直した
これでは「機能追加かバグ修正か」「破壊的変更を含むか」「どの領域の変更か」を判断できません。結果として、リリースノートを手で書いたり、変更を追うのに git show を何度も叩いたりといった非効率が発生します。
原因
本質的な原因は「メッセージの書式がルール化されておらず、ルールがあっても強制されていない」ことです。README に規約を書いても、人は忘れますし、レビューでも見落とします。規約(ルール)・検証(lint)・入力支援(prompt) の3つを揃えて初めて運用に乗ります。
対応方法
Conventional Commits の形式
<type>(<scope>): <subject> <body> <footer>
type: 変更の種類。feat/fix/docs/style/refactor/perf/test/build/ci/chore/revertscope: 影響範囲(任意)。例feat(auth):subject: 要約(命令形・現在形で簡潔に)body: 変更の理由・背景(任意)footer:BREAKING CHANGE:や課題番号など(任意)
例:
feat(auth): add refresh token rotation Refresh tokens are now rotated on every use to limit the blast radius of a leaked token. BREAKING CHANGE: refresh endpoint now returns a new token
1. commitlint を導入する
npm install --save-dev @commitlint/cli @commitlint/config-conventional
// commitlint.config.js
module.exports = {
extends: ['@commitlint/config-conventional'],
};
手動で検証できます。
echo "fix: typo" | npx commitlint # 合格(出力なし) echo "修正した" | npx commitlint # エラー
2. husky でコミット時に自動検証する
毎回手で叩くのは現実的でないので、Git フックに仕込みます。
npm install --save-dev husky npx husky init echo 'npx --no -- commitlint --edit "$1"' > .husky/commit-msg
husky v9 ではフックファイルに実行したいコマンドだけを書けば十分です(シェバングやブート行は不要)。$1 にはコミットメッセージファイルのパスが渡ります。package.json に prepare スクリプト(husky)が入っていることも確認してください。
これで規約違反のコミットは、コミット自体が失敗します。
git commit -m "直した" # ✖ subject may not be empty [subject-empty] # ✖ type may not be empty [type-empty] # husky - commit-msg script failed (code 1)
3. commitizen で入力を支援する
規約を暗記していなくても、対話で選ぶだけで正しい形式になるようにします。
npm install --save-dev commitizen cz-conventional-changelog
{
"config": {
"commitizen": { "path": "cz-conventional-changelog" }
},
"scripts": {
"commit": "cz"
}
}
git commit の代わりに npm run commit を使うと対話プロンプトが起動し、type の選択・scope・subject・body・破壊的変更の有無を答えるだけで、規約準拠のメッセージが自動生成されます。commitizen が形を保証し、commitlint が最終チェックする二段構えです。
実装例
. ├── .husky/commit-msg ├── commitlint.config.js └── package.json
// commitlint.config.js
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
// [レベル, 適用条件, 値] レベル: 0=無効 1=warning 2=error
'subject-case': [0], // 日本語 subject を許容
'header-max-length': [2, 'always', 72],
'scope-enum': [2, 'always', ['auth', 'api', 'ui', 'db', 'ci', 'deps']],
},
};
scope-enum を使うと scope を列挙値のみに制限でき、auth と authentication のような表記ゆれを防げます。
確認方法
導入が効いているかは、わざと違反を作って弾かれることを確認するのが確実です。
git commit --allow-empty -m "test" # 失敗する git commit --allow-empty -m "chore: verify setup" # 成功する npm run commit # 対話が起動する
CI でも検証したい場合は、範囲指定でまとめてチェックできます。
- name: Lint commit messages
run: npx commitlint --from=${{ github.event.pull_request.base.sha }} --to=${{ github.event.pull_request.head.sha }} --verbose
注意点
- husky はローカルフックなので
git commit --no-verifyで素通しできます。CI 側でも commitlint を走らせるのが安全です。 - 既存リポジトリに後から導入する場合、過去コミットは検証対象外です(フックは今後のコミットにのみ効きます)。過去履歴を lint するなら
--from/--toを明示します。 - 日本語の subject を使う場合は
subject-caseが引っかかることがあるため、ルールを上書きします。 - commitizen は強制できません(入力支援です)。直接
git commitする人がいても commitlint が最終検証するので整合性は保たれます。
まとめ
- 規約(Conventional Commits) を決め、検証(commitlint)・自動実行(husky)・入力支援(commitizen) を揃えると、コミットメッセージ運用は仕組みで回ります。
- 人の意志に頼らず、違反コミットを機械的に弾き、入力は対話で支援する。これが継続のコツです。
- 整った履歴は
semantic-releaseなどによる自動バージョニング・自動リリースノート生成の土台にもなります。まずは形式を揃えるところから始めましょう。
