サンプルコードで身につける: コミットメッセージ — 「なぜ」が伝わる書き方

解説で学んだ概念を、5つの具体例で確認します。素朴な例から実務寄りの例へと進みます。

1悪いメッセージと良いメッセージ

「修正」だけのメッセージは、1週間後の自分にもレビュアーにも何も伝えません。何をなぜ変えたかが1行で分かるように書くと、履歴がそのままプロジェクトの記録になります。

# ── 悪い例: 差分を開かないと何も分からない ──
git commit -m "修正"
git commit -m "いろいろ更新"
git commit -m "wip"

# ── 良い例: 1行で変更の内容と種類が分かる ──
git commit -m "fix: 連打するとお気に入りが二重登録される問題を修正"
git commit -m "feat: お気に入り一覧に並び替え機能を追加"
git commit -m "refactor: お気に入りの状態管理をサービスに集約"

2Conventional Commits の接頭辞

type: 説明という形式で書くのが Conventional Commits です。接頭辞を見るだけで変更の種類が分かるので、履歴の検索やリリースノートの自動生成にも使えます。

# 形式: <type>: <説明>

# よく使う type:
git commit -m "feat: お気に入りボタンを追加"        # 新機能
git commit -m "fix: 保存失敗時にエラー表示を出す"   # バグ修正
git commit -m "refactor: 重複した判定処理を関数化"  # 動作を変えない整理
git commit -m "docs: READMEに起動手順を追記"        # ドキュメント
git commit -m "test: お気に入り切り替えのテスト追加" # テスト
git commit -m "chore: 依存パッケージを更新"         # 雑務的な変更

# fix の履歴だけを探す、といった検索がしやすくなる
git log --oneline --grep="^fix"

3「なぜ」は本文に書ける

1行に収まらない理由や経緯は、コミットメッセージの本文に書けます。-m を2回渡すと1行目が要約、2つ目が本文になります。コードに書きにくい判断の理由を残す場所です。

# -m を2回渡す: 1つ目が要約(1行目)、2つ目が本文
git commit -m "fix: お気に入り保存のリトライを3回までに制限" \
  -m "サーバー障害時に無限リトライとなり、APIに負荷をかけていた。
3回失敗したらエラー表示に切り替え、ユーザーに再操作を促す方針にした。"

# 履歴で本文まで確認する
git log
# commit a1b2c3d...
#     fix: お気に入り保存のリトライを3回までに制限
#
#     サーバー障害時に無限リトライとなり、APIに負荷をかけていた。
#     3回失敗したらエラー表示に切り替え、ユーザーに再操作を促す方針にした。

# 「なぜこの実装なのか」は差分に写らない。本文が唯一の記録になる

41コミット=1つの変更に分ける

バグ修正のついでに別の整理もしたときは、git add でファイルを選んで2回に分けてコミットします。混ぜると片方だけ取り消したいときに分離できなくなります。

# 作業中にバグ修正と表記の統一の2つをやってしまった場合
git status
# modified: src/app/favorite.service.ts   # バグ修正
# modified: src/app/app.html              # 表記の統一

# ファイルを選んで、意味の単位で2回に分けてコミットする
git add src/app/favorite.service.ts
git commit -m "fix: 未ログイン時にお気に入りが消える問題を修正"

git add src/app/app.html
git commit -m "docs: ボタンの表記を『お気に入り』に統一"

# 分けておけば、後から片方だけ取り消す(revert)こともできる

5良い履歴は調査のときに効く

メッセージが整っていると、git log を眺めるだけで「いつ何が変わったか」を追えます。不具合がいつ混入したかを探すときに、履歴が読めるかどうかで調査時間が大きく変わります。

# 履歴を1行ずつ眺める
git log --oneline
# e5f6a7b feat: お気に入り一覧に並び替えを追加
# c3d4e5f fix: 連打で二重登録される問題を修正
# a1b2c3d feat: お気に入りをサーバーに保存

# 特定ファイルの変更履歴だけを追う
git log --oneline -- src/app/favorite.service.ts

# 「保存まわりがおかしい」→ 履歴が読めれば a1b2c3d 前後を
# 重点的に調べればよい、と当たりを付けられる。
# メッセージが「修正」の羅列だとこの絞り込みができない