commitlintとcommitizenで整えるコミットメッセージ運用

概要

コミットメッセージは「あとで読む誰か」のためのドキュメントです。しかし個人の裁量に任せると、fix・修正・とりあえず のような履歴が溜まり、git log から変更の意図が読み取れなくなります。

本記事では Conventional Commits を規約として採用し、

  • commitlint でメッセージ形式を機械的に検証し
  • husky でコミット時に自動でチェックを走らせ
  • commitizen で対話的に正しい形式のメッセージを作成する

という3点セットを、手を動かしながら構築します。ゴールは「規約を知らないメンバーでも、質問に答えるだけで規約準拠のコミットが打てる」状態です。

環境

本記事は以下を前提とします。

  • Node.js 20.x / npm 10.x
  • Git 2.40 以上
  • @commitlint/cli v19 系 / husky v9 系 / commitizen v4 系 / cz-conventional-changelog v3 系

発生していた問題

規約がないプロジェクトの 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 / revert
  • scope: 影響範囲(任意)。例 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 などによる自動バージョニング・自動リリースノート生成の土台にもなります。まずは形式を揃えるところから始めましょう。

\ 最新情報をチェック /

コメントを残す

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください。