はじめに
Chris Beamsさんの記事を読んで勉強したことをまとめたものです。
備忘録的に覚えておきたいことだけ掻い摘んでいるので、興味が湧いた方はぜひ原文をご覧ください。
Gitのコミットメッセージの書き方
以下、本文です。
よいコミットメッセージを書く理由
他人や未来の自分が、なぜこのコミットをしたのかを理解できるようにするためです。git diffでは差分を表示できますが、その理由はコミットメッセージしか教えてくれません。
それではどのようなコミットメッセージが推奨されるのか、一例を示します。
- わるいコミットメッセージ
$ git log --oneline -5 --author cbeams --before "Fri Mar 26 2009"
e5f4b49 Re-adding ConfigurationPostProcessorTests after its brief removal in r814. @Ignore-ing the testCglibClassesAreLoadedJustInTimeForEnhancement() method as it turns out this was one of the culprits in the recent build breakage. The classloader hacking causes subtle downstream effects, breaking unrelated tests. The test method is still useful, but should only be run on a manual basis to ensure CGLIB is not prematurely classloaded, and should not be run as part of the automated build.
2db0f12 fixed two build-breaking issues: + reverted ClassMetadataReadingVisitor to revision 794 + eliminated ConfigurationPostProcessorTests until further investigation determines why it causes downstream tests to fail (such as the seemingly unrelated ClassPathXmlApplicationContextTests)
147709f Tweaks to package-info.java files
22b25e0 Consolidated Util and MutableAnnotationUtils classes into existing AsmUtils
7f96f57 polishing
- よいコミットメッセージ
$ git log --oneline -5 --author pwebb --before "Sat Aug 30 2014"
5ba3db6 Fix failing CompositePropertySourceTests
84564a0 Rework @PropertySource early parsing logic
e142fd1 Add tests for ImportSelector meta-data
887815f Update docbook dependency and generate epub
ac8326d Polish mockito usage
前者は冗長でフォーマットが不定であり読みづらいですが、一方で後者は簡潔かつ一貫していて読みやすいです。差は明らかですが、意識せず自然に書いていると、どうしても前者のようになってしまいます。
それでは、どのようにすれば後者のようなコミットメッセージを書けるようになるのでしょうか。よいコミットメッセージには七つの法則があります。順番に説明しましょう。
よいコミットメッセージのための七つの法則
１．タイトルと本文を空行で区切ろう
まず、コミットをタイトルだけで済ませるか、本文も加えるか、という点を意識しましょう。誤字の修正などgit diffをすれば修正箇所や理由が明らかな場合は、以下のようにタイトルだけで構いません。
$ git commit -m "Fix typo in introduction to user guide"
しかし少しでも説明が必要となる場合は、コミット時に-mオプションを使わず、本文を加えましょう。本文の例を示します。
Derezz the master control program
MCP turned out to be evil and had become intent on world domination.
This commit throws Tron's disc into MCP (causing its deresolution)
and turns it back into a chess game.
さて、タイトルと本文を空行で区切る理由についてですが、単なる可読性の向上に留まりません。
Gitにはgit log --onelineやgit shortlogといった、タイトルだけを表示してくれる便利な機能がありますが、これらは空行でタイトルと本文を判別します。そのため空行を入れておかないと本文もタイトルとして扱われ、せっかくの--onelineオプションの意味がなくなってしまいます。
「わるいコミットメッセージ」のe5f4b49の例（一行目）がそのケースだと思われます。コミットメッセージが複数文から構成されてやたらと長いですが、その原因はタイトルと本文の間に空行がなかったためでしょう。
２．タイトルを50文字以内にしよう
長すぎないタイトルだと、git log --onelineしたときに読みやすいですね。何文字までが長すぎないのかは人によるかもしれませんが、Githubでは以下の仕様となっています。
- 50文字を超える場合：警告が表示される
- 72文字を超える場合：72文字に切り捨てられる
よって、できれば50文字、少なくとも72文字に収めましょう。
３．タイトルの先頭は大文字にしよう
単純ですが、大文字・小文字の使い分けに気をつけましょう。
４．タイトルの末尾にピリオドはやめよう
ピリオドを省略することで、一文字分タイトルに余裕ができます。タイトルを50文字以内に収めるためにも、不要なピリオドは省略しましょう。
５．タイトルには命令形を使おう
命令形はコマンドや指示を表すのに優れています。強い言葉に聞こえるので、遠慮する気持ちもあるかと思いますが、Git自体が「mergeしろ」「revertしろ」など命令形で語りかけてくるので、Gitのコミットメッセージで使用する分には問題ないでしょう。
また、活用形の揺れを抑えるためにも命令形（原形）は有効です。過去形や過去分詞形を使わず、命令形から始まるように書きましょう。より正確に言うならば、よいタイトルは以下のwillに続く文であるべきです。
- If applied, this commit will ...
たとえばRefactor subsystem X for readabilityというタイトルは、If applied, this commit will refactor subsystem X for readability.という文から導けます。このように命令形で始めることは、willのあとに続く原形から始めるという側面も持っています。
もちろん、本文においては命令形に固執することはありません。
６．本文では1行72文字以内に収めよう
git logをしたとき、長過ぎる文字を適度な場所で折り返してくれるかどうかは、環境に依存します。そのため、インデントの余裕を残して本文を72文字に収めましょう。
７．本文には方法よりも目的を書こう
まずはコミットの目的を明らかにしましょう。そして以下の３点を意識することが大切です。
- 変更前の動作
- 変更後の動作
- なぜその方法で解決しようとしたのか
方法はコードを見れば自明ですし、必要があればソースにコメントを書くことで補足しましょう。コミットメッセージにおいては、HowよりもWhatやWhyが大切です。
おわりに
本文は以上で終わりです。ここからは私的なことです。
自分ができていなかったことを振り返ってみます。
まず、コミットで本文を省略することが多かったですね。PRで説明すればいいかと思っていましたが、後からいちいちGithub開いて閉じたPRを探すのは大変な気もします。もちろんPRの方が情報量は多いですが、git logだけで解決できる選択肢を残しておくほうが親切ですね。反省です。
それから、willに続くようなタイトルを書けていませんでした。命令形を使ってた理由というのがなんとな〜くで、たまに過去分詞とか使っていました。fixedとか。あとは大文字にするのも割と忘れていた気がします。
なぜそういう「わるいコミットメッセージ」を書いていたのかというと、体系的に覚える機会がなく、そもそも意識できていなかったからだと思います。なので、今回一通り勉強した内容を忘れなければ、コミットの品質が上がるのではないかと期待しています。
有意義な取り組みでした。