Gitのコミットメッセージの書き方｜変更内容が伝わる基本と具体例

Gitで変更をコミットするとき、「メッセージに何を書けばよいのか」「件名だけで十分なのか」と迷うことがあります。「修正」「更新」だけでも作業したことは分かりますが、履歴を読む人には変更内容が伝わりません。

この記事では、Git初学者に向けて、コミット対象の差分を確認し、件名で変更を要約し、必要に応じて本文で理由を補う書き方を解説します。検索機能を題材に、変更別の具体例と履歴での確認方法を見ていきましょう。

Gitのコミットメッセージで伝える基本

何をどう変えたかを件名で伝える

コミットメッセージは、そのコミットに含まれる変更を説明する文章です。最初の行を件名として、対象と変更内容を簡潔に書きます。

たとえば、「検索処理を修正」では検索処理のどこが変わったのか分かりません。「空の検索条件を未指定として扱う」と書けば、入力条件と変更後の扱いが伝わります。ファイルを編集したという作業報告よりも、動作や構造がどう変わるかを表すと、後から差分を探す手掛かりになります。

ただし、件名にすべてを詰め込む必要はありません。一覧では変更の要点をつかめるようにし、理由や補足は本文へ分けます。

Gitの仕様とチームで決める慣習を分ける

Git自身は、コミットメッセージに日本語・英語、命令形、特定の文字数、Conventional Commitsの使用を強制しません。一方、チームでは読みやすさや自動処理のために規約を設けることがあります。

まずREADMEやCONTRIBUTINGなどを確認してください。メッセージを検査する仕組みが導入されていれば、チームの規約に合わないコミットが拒否される場合もあります。Git本体の制約と、リポジトリに追加されたルールを分けて考えましょう。

書く前にコミット対象の差分を確認する

ステージ済みの差分とメッセージを対応させる

通常の、ファイル名や-aを指定しないgit commitでは、ステージ済みの内容をコミットします。メッセージを書く前に、次のコマンドで状態と差分を確認します。

git status
git diff
git diff --cached

git statusでステージ済み・未ステージ・未追跡のファイルを把握し、git diffで追跡済みファイルの未ステージ差分、git diff --cachedでステージ済みの差分を読みます。未追跡ファイルの内容は通常のgit diffには表示されないため、ファイル自体も確認してください。

たとえば、検索処理とテストを編集しても、検索処理だけをステージしていれば、テストの変更はそのコミットに入りません。同じファイルでも、ステージ後に追加で編集した内容は未ステージのまま残ることがあります。

メッセージが説明するのは、作業中の変更全体ではなく、そのコミットに含める変更です。「テストを追加」と書くなら、対応するテストもステージ済みの差分に含まれているか確認します。

一文で説明しにくいときは変更の目的を整理する

「検索を追加し、別画面の表示を直し、READMEも更新」としか説明できないなら、独立した目的が混ざっていないか見直します。無関係な変更を分けると、それぞれの件名を具体的に書きやすくなります。

一方、検索機能の実装、対応するテスト、利用方法の説明は、一つの目的に必要な変更としてまとめられます。ファイル数や行数だけで分割せず、「このコミットで何を実現するか」を基準に考えてください。

件名と本文を使い分ける書き方

件名は対象と変更内容を簡潔に書く

件名は「対象＋どう変えるか」を基本にすると組み立てやすくなります。たとえば、「検索結果に更新日順の並び替えを追加」「検索条件の説明に入力例を追加」のように書きます。

「処理を改善」「各種対応」といった言葉だけでは対象が広すぎます。何の処理か、どの条件でどう変わるかを絞り込みましょう。逆に、長いファイルパスや実装の細部をすべて並べると、変更の要点が埋もれます。

件名の長さはチームの規約に合わせます。文字数を減らすために重要な条件を落とすより、補足を本文へ移して意味の通る一行に整えることが大切です。

本文は変更の理由・背景・影響を補う

小さく明確な変更なら、件名だけで十分な場合があります。たとえば「検索ボタンのラベルの誤字を修正」は、差分と合わせて目的を理解しやすい件名です。

一方、コードだけでは判断の理由が分からない変更には本文が役立ちます。なぜその扱いを選んだのか、どの条件に影響するのかを補います。次は、空文字を未指定として扱う仕様に合わせる場合のメッセージ例です。

空の検索条件を未指定として扱う

空文字が検索条件として渡されるため、条件未指定時と扱いが異なっていた。
空文字では絞り込みを行わない仕様に合わせ、条件判定を変更する。

空文字と条件未指定のケースをテストに追加する。

本文は件名の言い換えを重ねる場所ではありません。差分から読み取りにくい理由や影響を残します。また、「テストを追加した」と「テストを実行して成功した」は別の事実です。確認結果を書く場合は、実際に確認した範囲だけを記載してください。

件名と本文を空行で分けて入力する

件名と本文を書くときは、最初の一行を件名にし、その後に空行を入れます。ステージ済みの変更に対してgit commitを実行すると、設定されたエディタでメッセージを入力できます。保存や終了の操作は利用するエディタに従ってください。

git commit

件名だけなら、-mで指定する方法もあります。以下は、検索ボタンのラベル修正だけをステージした場合の例です。

git commit -m "検索ボタンのラベルの誤字を修正"

-mを複数指定すると、それぞれの値が別の段落として連結されます。次は、検索条件の判定変更をステージした場合に、件名と本文を分けて指定する例です。前の例と続けて実行する手順ではなく、変更内容に応じて使い分けます。

git commit -m "空の検索条件を未指定として扱う" -m "空文字では絞り込みを行わない仕様に合わせ、条件判定を変更する。"

変更内容が伝わるコミットメッセージの具体例

機能追加は何ができるようになるかを書く

機能追加では、利用者や呼び出し側が新しくできることを件名にします。「検索機能を変更」よりも「記事一覧にキーワード検索を追加」の方が、追加する機能と対象を読み取れます。

「使いやすくする」「便利にする」といった評価よりも、具体的に増える操作や変わる動作を書きます。まだ入力欄だけの実装なら、検索全体が完成したような件名にはしません。

不具合修正は発生条件と修正内容を書く

不具合修正では、「どの条件で起きる問題か」と「どう直すか」を意識します。件名に両方を収めにくいときは、識別に必要な条件を残し、詳しい原因や修正方針を本文へ書きます。

これらの件名は、それぞれの差分と期待する仕様が一致する場合の例です。原因を特定できていない段階で原因を断定したり、一部の条件への対応を「検索エラーをすべて解消」と広げたりしないようにします。

テスト・ドキュメント・リファクタリングは変更の目的を書く

画面の機能が増えない変更でも、何のための変更かを具体的に書けます。テストなら対象条件、ドキュメントなら追加・修正する説明、リファクタリングなら整理する構造を示します。

内部構造の整理と動作変更が同時に含まれる場合は、件名を「リファクタリング」だけで済ませず、動作の変化も説明してください。また、計測していない変更を「検索を高速化」と表現するより、「重複する検索呼び出しを削除」のように差分から確認できる内容を書く方が正確です。

「修正」「更新」だけの件名を具体化する

短い件名を具体化するときは、「何を」「どの条件で」「どう変えたか」を差分から拾います。すべての要素が必要とは限りませんが、他のコミットと区別できる情報を残しましょう。

たとえば「更新」なら対象を補って「検索の説明を更新」、さらに内容を補って「検索の説明に複数キーワードの入力例を追加」とします。「修正」という単語を禁止する必要はありません。「検索結果が0件のときの表示崩れを修正」のように、対象と条件があれば変更を読み取れます。

Conventional Commitsをチーム規約として使う例

type・任意のscope・説明で構成する

Conventional Commitsは、コミットメッセージの形式をそろえるための慣習です。採用する場合、件名は基本的に次の構成にします。Gitを使うすべてのチームに必須の形式ではありません。

<type>[optional scope]: <description>

typeは変更の種類、scopeは対象範囲、descriptionは変更の説明です。scopeは任意で、付ける場合は丸括弧で囲みます。コロンの後ろにはスペースを入れます。

feat: 記事一覧にキーワード検索を追加
fix(search): 空の検索条件を未指定として扱う

この二行は、それぞれ別のコミットの件名例です。scopeの候補をsearchなどの機能名にするか、パッケージ名にするかはチームでそろえます。形式を整えても説明が「更新」だけでは内容が伝わらないため、接頭辞の後ろも具体的に書いてください。

feat・fixとその他のtypeを使い分ける

Conventional Commits 1.0.0では、featは新機能、fixは不具合修正を表します。それ以外のtypeも使えますが、仕様が追加typeの一覧や意味をすべて固定しているわけではありません。

追加typeは、利用している検査ツールやリリース処理との対応も含めて決めます。たとえば、不具合修正とそのテストを一緒にコミットするなら、テストファイルが含まれるという理由だけでtestにせず、変更全体の目的から判断します。

破壊的変更の表記と採用範囲を決める

既存の利用方法との互換性を壊す変更は、破壊的変更として示します。Conventional Commitsでは、typeまたはscopeの直後の!、あるいはBREAKING CHANGE:で始まるfooterで表せます。両方を併記することもできます。

たとえば、検索APIのパラメータ名をqからqueryへ変更し、旧名を受け付けなくする場合は、次のように変更内容と移行先を示します。

feat(search)!: 検索APIのパラメータ名をqueryに統一

BREAKING CHANGE: 検索APIでqを受け付けなくなるため、呼び出し側はqueryへ変更する。

破壊的変更は、変更行数の多さではなく互換性への影響で判断します。featだけに限らず、他のtypeにも付けられます。

導入時は、使うtype、scopeの命名、説明の言語に加え、どのメッセージを検査するかも決めておきます。各コミットを対象にするのか、squashマージ後に残すメッセージを対象にするのかで運用は変わります。規約に合わせて検査やリリースの仕組みを設定してください。

コミット履歴とレビューで読みやすさを確認する

git logで件名の一覧と本文を確認する

メッセージは入力した画面だけでなく、履歴の一覧でも確認します。--onelineを使うと、コミットを簡潔な一行形式で表示できます。

git log --oneline -5

直近5件を並べて、件名だけでそれぞれの目的を区別できるか見ます。「修正」「追加修正」が続いているなら、どの対象をどう変えたか補える余地があります。

直近のコミットの件名と本文を読むには、次のように指定します。

git log -1 --format=%B

一覧で要点が分かり、本文を読むと理由や背景を補える構成になっているか確認しましょう。

メッセージと実際の変更が一致しているか見直す

コミット後は、メッセージと差分を一緒に確認します。直近のコミットを確認するなら、次のコマンドを使えます。

git show HEAD

「空の検索条件を未指定として扱う」という件名なら、その判定変更が含まれているか、本文に書いたテストも含まれているかを確認します。反対に、別機能の修正や不要な整形が混ざっていないかも見直します。

コミット単位で確認できたら、作業ブランチ全体の差分やPR前の確認へ進みます。ブランチ作成からpush・レビュー依頼までの流れは、次の記事で整理しています。

あわせて読みたい

Gitブランチ運用入門｜feature・fixの分け方とPR前の確認 Git初学者やチーム開発に参加したばかりの方向けに、feature・fixの命名例、ブランチ作成・切替・push、小さなPRの作り方を解説。差分・秘密情報・テストの確認から、GitHubでのレビュー依頼、コンフリクトや強制pushの注意点まで整理します。

レビュー対応は何を変えたかが分かる名前にする

レビュー後の追加コミットも、「レビュー対応」「指摘修正」だけで済ませず、対応内容を件名にします。たとえば「検索条件の正規化を専用関数へ分離」「検索条件が空白のみの場合のテストを追加」と書けば、履歴から変更を追えます。

レビューコメントへの返信では対応した箇所を伝え、コミットメッセージには変更自体の説明を残します。コメントを読まなくても意図が伝わる形にしておくと、後から履歴を調べるときにも役立ちます。共有済みのコミットを書き換えるかどうかは、チームの履歴管理ルールに従ってください。

まとめ

Gitのコミットメッセージは、ステージ済みの差分を確認し、その変更を一文で説明するところから始めます。件名には対象と変更内容を書き、件名だけでは伝わらない理由・背景・影響を本文で補いましょう。

文字数、使用言語、命令形、接頭辞は、Gitの必須条件とチームの規約を区別します。Conventional Commitsを採用する場合も、形式を守ることに加えて、説明が実際の差分と一致していることが大切です。

コミット後はgit logで件名の並びと本文を読み、git showで差分と照合します。「修正」「更新」で終わらせず、後から読む人が変更の目的をつかめるメッセージを残してください。