Git コミットメッセージの書き方｜文字数の目安とベストプラクティス
Git のコミットメッセージは、コードの変更履歴を読み解くための重要な手がかりです。適切に書かれたメッセージは、数か月後のコードレビューやバグ調査を大幅に効率化します。一方で、曖昧なメッセージは技術的負債となり、チーム全体の生産性を低下させます。この記事では、コミットメッセージの文字数の目安と、実務で役立つベストプラクティスを解説します。メッセージの文字数確認には 文字カウンタス をご活用ください。
コミットメッセージの基本構造と文字数の目安
Git コミットメッセージは「件名 (subject)」と「本文 (body)」の 2 部構成が標準です。件名と本文の間には空行を 1 行挟みます。この構造は git log --oneline や GitHub のコミット一覧で件名だけが表示される仕組みに対応しています。
| 要素 | 文字数の目安 | 理由 |
|---|---|---|
| 件名 (subject) | 50 文字以内 (英語) | GitHub の一覧表示で途切れずに表示される長さ |
| 件名 (ハードリミット) | 72 文字以内 | 72 文字を超えると GitHub 上で省略記号 (...) が付く |
| 本文の 1 行あたり | 72 文字で折り返し | ターミナルの標準幅 (80 桁) でインデント分を考慮した値 |
| 本文全体 | 制限なし | 必要に応じて詳細な説明を記述可能 |
日本語でコミットメッセージを書く場合、全角文字は表示幅が英語の約 2 倍になるため、件名は 25 文字程度を目安にすると GitHub 上で見切れにくくなります。
Conventional Commits とプレフィックスの使い方
Conventional Commits は、コミットメッセージに統一的な構造を持たせる規約です。メッセージの先頭にプレフィックス (型) を付けることで、変更の種類が一目で判別でき、CHANGELOG の自動生成やセマンティックバージョニングとの連携も可能になります。
基本フォーマットは <type>(<scope>): <description> です。scope は省略可能で、変更対象のモジュールやコンポーネントを示します。
| プレフィックス | 用途 | 例 |
|---|---|---|
feat |
新機能の追加 | feat(auth): add OAuth2 login support |
fix |
バグ修正 | fix(api): resolve null pointer in user endpoint |
docs |
ドキュメントの変更 | docs: update API reference for v2 |
style |
コードスタイルの変更 (動作に影響なし) | style: fix indentation in config file |
refactor |
リファクタリング | refactor(db): simplify query builder logic |
test |
テストの追加・修正 | test: add unit tests for payment module |
chore |
ビルドやツールの変更 | chore: upgrade webpack to v5 |
perf |
パフォーマンス改善 | perf(search): add index for full-text query |
ci |
CI/CD 設定の変更 | ci: add GitHub Actions workflow |
プレフィックスを使うことで、git log --oneline の出力を眺めるだけで変更の全体像を把握できます。チーム開発では、プレフィックスの種類と使い分けをドキュメント化しておくと運用がスムーズです。
良いコミットメッセージと悪いコミットメッセージの比較
コミットメッセージの品質は、プロジェクトの保守性に直結します。以下に、実務でよく見かける悪い例と、改善した良い例を対比して示します。
| 悪い例 | 問題点 | 良い例 |
|---|---|---|
fix bug |
何のバグか不明 | fix(cart): prevent duplicate items on rapid click |
update |
何を更新したか不明 | docs: add setup instructions for local dev |
WIP |
作業途中のコミットが履歴に残る | feat(ui): add skeleton loader for product list |
asdfgh |
意味のない文字列 | refactor: extract validation logic into helper |
Fixed the thing that was broken in the last commit because it was not working properly |
冗長で 50 文字を大幅に超過 | fix(auth): restore session after token refresh |
- 件名は命令形で書く: 「Added」ではなく「Add」、「Fixed」ではなく「Fix」を使う。Git 自体が生成するメッセージ (Merge branch...) と文体が統一される
- 件名の末尾にピリオドを付けない: スペースの節約と慣例の両面から推奨される
- 「なぜ」を本文に書く: 件名は「何をしたか」、本文は「なぜその変更が必要だったか」を記述する
- 1 コミット = 1 論理的変更: 複数の無関係な変更を 1 つのコミットにまとめない
チーム開発でのコミットメッセージ運用ルール
個人開発ではメッセージの書き方に自由度がありますが、チーム開発では統一されたルールが不可欠です。以下の施策を導入すると、メッセージの品質を組織的に維持できます。
- commitlint の導入: Conventional Commits の規約に沿っているかを自動チェックするツール。CI に組み込めば、規約違反のコミットをマージ前に検出できる
- Git hooks (husky) の活用:
commit-msgフックでローカル環境でもメッセージのフォーマットを検証する - テンプレートの設定:
git config commit.templateでチーム共通のテンプレートを設定し、記述漏れを防ぐ - コードレビューでメッセージも確認する: プルリクエストのレビュー時に、コミットメッセージの品質もチェック対象に含める
ルールを厳格にしすぎると開発速度が落ちるため、チームの規模や文化に合わせて段階的に導入するのが現実的です。まずはプレフィックスの統一から始め、慣れてきたら commitlint を導入するといった段階的なアプローチが効果的です。
まとめ
Git コミットメッセージは、件名 50 文字以内・本文 72 文字折り返しが広く受け入れられている慣例です。Conventional Commits のプレフィックスを活用すれば、変更の種類が一目で分かり、CHANGELOG の自動生成にも対応できます。良いメッセージは「何を」「なぜ」変更したかを簡潔に伝え、悪いメッセージは曖昧で情報量が不足しています。コミットメッセージの文字数を確認する際は、文字カウンタス をぜひご活用ください。