Commit Hygiene（コミットの衛生管理）
概要
Jarrett のルール第 4 条: 1 つの変更には、論理的に必要なコミットだけを含める。レビュアーは各変更に対して、試行錯誤の履歴ではなく、1 つのクリーンなコミットを読む。コメントは短くする。
commit-check フックは、git commit メッセージが制限を超えた場合に警告を出します。ブロックはしません。あなたがコミットを修正します。
使用するタイミング
- 各コミットの前。
- 各プッシュの前。
- 1 つの問題を修正するために複数のコミットを作成した場合。
commit-checkフックが警告を出した場合。
手順
1. メッセージを書く
- 件名: 72 文字以内。命令形を使用する: 「Added rules hook」ではなく「Add rules hook」。
- 本文: 5 行以内。件名だけで十分な場合は本文を省略する。
- 何が変わったのか、なぜ変わったのかを書く。各ファイルの説明はしない。
- 簡略化された英語を使用する。
simplified-englishスキルを参照。
2. 論理変更ごとに 1 コミット
- 1 つの論理変更: レビュアーが 1 つの単位として承認または却下できる、機能の一部、修正、リファクタリング。
- 1 つのコミットにリファクタリングと振る舞いの変更を混在させない。
- 試行錯誤のコミットはしない。変更が動作し、テストが通ったときにコミットする。
3. プッシュ前に fix-up コミットを squash する
fix-up コミットは、同じ変更内の以前のコミットを修正するものです。例：「fix typo」「wip」「address review」。
git commit --fixup <sha>で fix-up コミットを作成する。- エディターなしで squash する:
GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash <base>。 - リベースがコンフリクトで停止した場合、ファイルを修正して
git add <files>を実行する。その後GIT_EDITOR=true git rebase --continueを実行する。中止するにはgit rebase --abortを実行する。 - 再度テストを実行する。
- 結果を確認する:
git log --oneline <base>..HEAD。
最後のコミットが修正対象の場合、git commit --amend --no-edit を使用する。
警告: 共有ブランチ上にあるコミットを書き換えないこと。まずユーザーに確認すること。書き換えはチームメイト全員にリセットを強制します。
4. コメントを短く保つ
- コードが明確でない場合のみコメントを書く。
- 通常は 1 行で十分。何をしているかではなく、なぜそうしているかを書く。
- コメントに変更履歴を書かない。Git が履歴を保持する。
よくある言い訳
| 言い訳 | 現実 |
|---|---|
| 「小さなコミットは進捗を示す」 | レビュアーが必要とするのは結果であり、道のりではない。試行錯誤のコミットは squash せよ。 |
| 「長いメッセージはより多くの文脈を提供する」 | 長いメッセージは読まれない。文脈は仕様書または PR に書け。 |
| 「後で squash する」 | 後はプッシュ後だ。プッシュ前に squash せよ。 |
| 「フックは警告するだけだから、制限は任意だ」 | 制限はチームのルールだ。フックは修正できるように警告している。 |
警告サイン
- プッシュ前に
git logに「wip」「fix」「oops」「try again」が表示される。 - 1 つのバグ修正に対して複数のコミットがある。
- コミット本文に変更された各ファイルが列挙されている。
- コードが言っていることを繰り返すだけのコメント。
確認項目
- 各件名が 72 文字以内で、命令形を使用している。
- 各本文が 5 行以内である。
-
git log --oneline <base>..HEADが論理変更ごとに 1 コミットを示している。 - プッシュ前に fix-up コミットが残っていない。
- リベース後もテストが通る。
既知の制限: フックは git -C <dir> commit や git -c <key>=<value> commit をチェックしません。また、-F <file> など、読み取れない一部のメッセージはスキップします。