コミットメッセージのベストプラクティス

良いコミットメッセージとはどのようなものか、書き方のベストプラクティスを整理します。

1. 良いコミットメッセージとは

コミットメッセージは、変更内容を他の開発者や未来の自分に伝えるためのものです。数か月後にコミット履歴を見返したとき、どのような変更がなぜ行われたのかを理解できるかどうかは、コミットメッセージの書き方にかかっています。チーム開発においても、他のメンバがコミット履歴を追って変更の経緯を把握する場面は頻繁にあるため、誰が読んでも内容が伝わるコミットメッセージを書くことが重要です。

以下は、良いコミットメッセージの例です。

feature: ログ解析ツールにCSV出力機能を追加

解析結果をCSV形式でエクスポートする機能を実装。
--csv オプションで出力先のパスを指定できる。

このメッセージが優れている点は、1行目で変更の種別(feature=新機能)と概要が簡潔にまとまっており、一覧表示でも内容がひと目で把握できることです。さらに、2行目以降の詳細説明で具体的な実装内容やオプションの使い方が補足されているため、変更の目的と影響範囲を正確に理解できます。

なお、コミットメッセージにはGitが強制する文字数の上限はありませんが、広く採用されている慣例として、1行目(件名)は50文字以内に収めることが推奨されています。これは、GitHubのコミット一覧やプルリクエスト上では1行目が長いと途中で省略表示されてしまうためです。また、git log --onelineでも1行目のみが表示されるため、短く要点をまとめることで、履歴を素早く確認できるようになります。詳細な説明が必要な場合は、1行目の後に空行を挟んでから本文を記述し、各行は72文字程度で折り返すのが一般的です。

一方、以下は悪いコミットメッセージの例です。

修正
色々変更した

これらのメッセージは、何を修正したのか、何を変更したのかがまったくわかりません。後からコミット履歴を見返しても、実際にコードの差分を開いて確認しなければ変更内容を把握できず、効率的な開発の妨げになります。「修正」であれば「fix: ログイン時にセッションが保持されないバグを修正」のように、何をどう修正したのかを具体的に記述しましょう。

2. コミットメッセージの構成

一般的に採用されているコミットメッセージの形式です。

<種別>: <概要>

<詳細な説明(任意)>

よく使われる種別(プレフィクス)は以下のとおりです。

種別 用途 メッセージ例
feature 新機能の追加 feature: ログ解析ツールにCSV出力機能を追加
fix バグ修正 fix: ログイン時にセッションが保持されないバグを修正
docs ドキュメントの変更 docs: READMEにセットアップ手順を追記
refactor リファクタリング(機能変更なし) refactor: ユーザ認証処理を関数に分離
test テストの追加・修正 test: ログ解析の異常系テストを追加
chore ビルドや設定の変更 chore: .gitignoreにvenv/を追加

3. コミットの粒度

コミットは1つの論理的な変更ごとに作成するのが望ましいです。たとえば、「ログ解析のエラーハンドリングを追加」のように、1つの明確な目的に対応したコミットであれば、履歴を見返したときに変更の意図がすぐに理解できます。

一方、「ログ解析ツール全体を実装」のように1回のコミットに多くの変更をまとめてしまうと、複数の変更が混在して追跡しづらくなります。もし後から一部の変更だけを取り消したくなっても、他の変更と絡み合っているため対応が困難になります。

逆に、「変数名を1つ変更」のようにあまりに小さな単位でコミットを作成すると、コミット履歴が膨大になり、意味のあるまとまりとして変更を追跡することが難しくなります。

適切な粒度でコミットすることで、git logで変更履歴を追いやすくなり、問題が発生した際にgit revertで特定のコミットだけを取り消すことも容易になります。「このコミットで何をしたかを一文で説明できるか」を目安にすると、適切な粒度を判断しやすくなります。

💡 ポイント
コミットメッセージを日本語で書くか英語で書くかは、プロジェクトやチームのルールによって異なります。海外展開を見据えているプロジェクトや、チーム内に海外のメンバがいる場合などは、コミットメッセージを英語で統一しているケースがあります。一方で、日本語でコミットメッセージを書いているプロジェクトも数多くあります。「コミットメッセージは英語で書くもの」という印象を持っている方もいますが、重要なのはプロジェクトの既存のルールに合わせることです。チーム全体が日本語でコミットメッセージを書いている中で、自分だけ英語で書いてしまうと、他のメンバが変更内容をすぐに把握しづらくなり、かえってチームの生産性を下げてしまいます。新しいプロジェクトに参画した際は、過去のコミット履歴を確認し、どちらの言語で書かれているかを把握した上で、それに合わせるようにしましょう。