Gitのコミットメッセージを書く：変更の目的と検証結果を残す

コミット一覧に「修正」「完了」「最終」しか残っていないと、数週間後に同じ問題に遭遇したとき、どの変更を探せばよいか分かりにくくなります。コードの差分は何を変えたかを示しますが、その選択の理由や確認できなかった範囲まで自動的に説明してくれるわけではありません。コミットメッセージは、未来の自分や同僚が変更を理解できるよう残す短い説明書です。この記事では、小さなバグ修正を例に、タイトル、本文、検証記録の構成方法を見ていきます。

1. まず1つのコミットで説明する問いを定める

メッセージを適切に書くには、変更のまとまりが説明できる大きさでなければなりません。例えば検索結果で空文字列を扱うコードとログイン画面の色の変更を同時に含めると、「検索結果のエラー修正」というタイトルでは変更全体を説明できません。2つの作業の目的と元に戻す理由が独立しているなら、別々のコミットに分けたほうが記録を見つけやすくなります。ファイル数が多いだけで必ず分ける必要はありません。同じ問題を解決するためにコード、テスト、説明文書を一緒に変更したなら、1つの目的を持つ場合があります。

作業後にタイトルを無理に付けるのではなく、「どのような状況で問題が起きたか」「今回の変更はその状況をどう扱うか」をそれぞれ1文で書いてみてください。この2文を結び付けられないなら、作業範囲がまだ不明確かもしれません。一時的なデバッグ出力や無関係な書式変更が混ざっていないかも確認します。コミットメッセージで変更の混在を隠すより、実際のまとまりを整理することが先です。

2. タイトルは変更を識別し、本文は理由を説明する

Git公式ドキュメントは、短いタイトルの後に空行を入れ、詳しい説明を続ける構成を案内しています。およそ50文字以内のタイトルは読みやすさのための推奨であり、すべてのプロジェクトに適用される保存制限ではありません。韓国語のタイトルを英語の基準に機械的に合わせるよりも、チームの規則を確認し、一覧で核心が読み取れるよう書いてください。タイトルだけでも変更の対象と動作が分かるとよいでしょう。

例えば「バグ修正」ではなく「検索語が空白の場合は結果リクエストを省略」と書けば、条件と動作がともに分かります。「検索性能を大幅に改善」のように測定が必要な表現は、実際の根拠がなければ避けます。「すべてのエラーを解決」も確認範囲を超える場合があります。タイトルには今回のコミットが行ったことを書き、今後行う作業や未解決の問題は本文に別途残します。

項目	記載する内容	説明用の例
タイトル	対象と変更の動作	検索語が空白の場合は結果リクエストを省略
問題	変更前の具体的な条件	空白だけを入力しても検索リクエストが作られる
理由	この方法を選んだ理由	リクエスト前に正規化して不要な呼び出しを減らす
検証	実際に確認した項目と結果	空入力・空白入力・通常入力の事例を確認
残る範囲	未確認または別途対応する部分	実際のサーバー応答とモバイル画面は未確認

3. 実際に行っていない検証結果は記さない

次は記載形式を示す架空のメッセージです。ここに記した動作確認は、実際のプロジェクトの試験結果ではありません。使う際は、自分の作業で実施した項目に置き換えてください。特にAIが下書きを作った場合は、実行していないテストコマンドや「すべてのテストに合格」という文言が含まれていないか確認する必要があります。作成者が予想した動作と、実行して確認した動作は区別して記録します。

검색어가 공백일 때 결과 요청 생략

문제: 공백만 입력해도 검색 요청이 생성된다.
변경: 입력을 정리한 뒤 길이가 0이면 요청을 생략한다.
이유: 결과 처리 단계보다 요청 생성 단계에서 조건을 판단한다.

검증: 이 줄에는 실제 수행한 확인 항목과 결과를 적는다.
미확인: 실제 서버 연동과 모바일 화면은 별도 확인이 필요하다.

検証記録には「確認完了」だけでなく、条件と結果を組にして書くとよいでしょう。例えば通常の検索語では既存の呼び出しが維持されたか、空白では呼び出しが省略されたか、エラー時には既存のエラー表示が維持されたかを分けると、後で回帰問題を見つけやすくなります。失敗したテストを記録する場合は、失敗理由を推測として示し、合格したように書き換えません。

まだ実行できていなくても、有用なメッセージは書けます。「検証：コード差分を確認。実行試験は未実施」のように現段階を明示し、実行する項目を別の一覧に残してください。テストコードを追加した事実と、そのテストを実行した事実も異なります。前者は変更内容、後者は検証記録です。この区別は、同僚が次に行うことを決める際に直接役立ちます。

4. 保存前にステージング範囲と説明を照合する

基本的なコミットは、ステージング領域に準備された内容を記録します。エディターでファイルを保存しただけで、そのファイルの最新の変更すべてが今回のコミットに含まれると思うと、メッセージと実際のコードが食い違う場合があります。部分的に準備した変更があれば、同じファイル内でも含まれる行と残る行が異なることがあります。使用するGit画面で今回のコミットに含まれる差分を読み、メッセージで説明する変更がその範囲内にあるか確認してください。

メッセージの確認は、3回の照合で簡単に進められます。まずタイトルに記した動作が実際の差分に見えるかを確認します。次に本文で説明した理由がコードの条件やコメントと矛盾しないかを確認します。最後に変更した公開インターフェースや文書があれば、説明から抜けていないか確認します。パスワード、トークン、実際の顧客資料など、記録に残すべきでない内容を例やログから取り除く作業も、この段階に含まれます。

ただしコミットメッセージを完璧に整えるために、無関係なコードを追加で修正する必要はありません。見つけた別の問題は次の作業として残し、現在の目的を明確にします。「検索リクエスト条件の修正」に含まれる文書変更がその条件を説明するためなら一緒に説明できますが、文書全体の文体改訂は別の目的です。元に戻す際に一緒に戻すべき変更かを考えると、まとまりを判断しやすくなります。

5. 長いメッセージはエディターやファイルで作成する

短いメッセージはgit commit -m "検索語が空白の場合は結果リクエストを省略"のように渡せます。複数の段落が必要なら、既定のエディターを使うか、UTF-8のテキストファイルにメッセージを書き、git commit -F commit-message.txtで読み込む方法が便利です。これらのコマンドは現在のリポジトリに実際のコミットを作るため、この記事の例を実行する前に、準備された変更範囲を確認する必要があります。

メッセージファイルには、1行目にタイトル、次の行に空行、その後に説明を入れます。ファイル中の文言をそのまま記録する意図があるか確認してください。エディター用テンプレートの案内文がファイルにも残っていると、不要な説明が記録される場合があります。長いメッセージをシェルの1行の文字列に移す際に改行や引用符を失う場合は、ファイルを使うほうが読みやすく、確認しやすくなります。チームで定めたテンプレートがあるなら、その形式を優先します。

毎回同じ項目でメッセージを書きたいなら、「問題・変更・検証・未確認」の4行のひな型から始めてください。すべての項目を必ず長文で埋める必要はありません。単純な誤字修正は1行のタイトルで十分な場合があり、外部APIの動作やデータ形式を変更する作業には、適用条件と互換性の説明が必要な場合があります。記録の長さは、変更のリスクと説明に必要な情報に合わせるとよいでしょう。

6. 一覧と詳細画面で読み取れるかを確認する

git log -5 --onelineは、最近のコミットを短い識別子とタイトルを中心に表示する読み取りコマンドです。この画面で「修正」「追加」「完了」というタイトルが続くと、検索しにくい記録になります。本文が長くても一覧にはタイトルしか見えない場合が多いため、タイトルに対象と動作を含める理由はここにあります。詳細な説明が必要なら、通常のgit log -1で最近のコミットメッセージを読めます。

一覧で次の3つを問いかけてください。検索入力の問題を探す人がこのタイトルを選べるか、UIの色変更と区別できるか、今回の変更が追加・修正・削除のどれなのか理解できるか。タイトルを理解するために本文を開く回数が減ると、記録の有用性が高まります。コミットハッシュは変更を識別しますが、問題の意味まで説明しないため、人が読めるタイトルも必要です。

7. 接頭辞とイシュー番号はプロジェクトの規則に合わせる

fix:、feat:、docs:などの接頭辞は、チームやツールが定めた規則の場合があり、Gitがすべてのリポジトリに強制する構文ではありません。自動リリースツールがメッセージを読むプロジェクトなら、そのツールの規則を先に確認してください。個人のリポジトリでは、接頭辞を多く増やすより、一貫して使ういくつかの分類を定めるだけで十分な場合があります。接頭辞が正確でも、タイトルが「その他の修正」なら内容を見つけにくくなります。

イシュー番号を付ける際も、番号だけでなく核心となる問題を文章で説明します。後でイシュー管理システムにアクセスできなくなったり、リポジトリを別途保存したりしても、変更を理解できるためです。実際の問題の詳細記録はイシューに、今回のコミットの選択と検証範囲はメッセージに置くと、役割が明確になります。イシューを自動終了する構文はサービスによって異なる場合があるため、未確認のキーワードを惰性で入れません。

8. すぐ使える最終確認表

• タイトルに変更対象と動作があるか？
• タイトルの後に空行を入れて本文を区別したか？
• 変更前に問題が起きた条件を具体的に記したか？
• コード差分だけでは分かりにくい選択理由を説明したか？
• 検証記録は実際に実施した項目と一致するか？
• 実行できなかった範囲を合格と表現していないか？
• 準備された変更とメッセージの範囲は一致するか？
• チームの規則とイシューの関連付け方法に合っているか？

よい記録は、大げさな文体ではなく、検索できる条件と信頼できる確認範囲から生まれます。今日のメッセージを、未来にエラーを分析する人が読むと考えてみてください。「なぜこの条件を追加したか」と「どこまで確認したか」が残っていれば、コードの変化が判断の根拠になります。最初は短いタイトルと2、3文の本文から始め、説明が必要な変更だけで内容を広げる方法が実用的です。

公式出典と執筆基準

• Git公式ドキュメント：git commit
• Git公式ドキュメント：git log

資料確認日：2026-10-10。実際に開いた公式資料をもとにAIが作成した説明です。別途示した計算・コード・確認事例は説明用であり、ユーザー環境を直接試験した結果や実測結果ではありません。公開日には機能と資料の変更の有無を再確認します。

コミット記録を作る順序

1. 問題の条件と変更目的を整理

→

2. コミットに含める差分を確認

→

3. タイトル → 空行 → 理由を書く

→

4. 実際の検証と未確認範囲を記録

→

5. 保存後に一覧と詳細メッセージを確認

本文を説明するための図解であり、実際の製品画面や測定資料ではありません。