Git でより良いコミットメッセージを書く方法

Git で管理しているプロジェクトのソースコードを色々変更して, いざコミットという時にどういった変更をしたのかを説明するためにコミットメッセージというものを書きますよね.

例えば次のコマンドで, メッセージ付きでコミットできます:

git commit -m "Your commit message here."

こうしてメッセージを残しておくことによって後々 git log コマンドなどでどんな変更をしてきたかを知ることができます.

それほど詳しい説明がいらない, 一行のメッセージで十分コミットの内容を使えることができるようなコミットでしたらそれでもいいのでしょう.

でもより詳しい説明を付け加えないとコミットの内容が理解しづらいという場合は, より良いコミットメッセージの残し方があるんです.

それは git commit コマンドに -m オプションを付けないでそのまま実行してしまうんです.

そうすると .gitconfig の core.editor で指定されたエディタが起動するので, そのエディタでコミットメッセージを書くことができます.

ではどんなふうに書いた方がいいのかということなのですが, 例として次のようなコミットメッセージを考えてみました:

Show a thanks message after a user submits a reply

If a user submitted a reply on the comment form, no "Thank you" message
wouldn't be displayed, which lacked a bit of courteousness.

Thus now a "Thank you" message will be displayed if a user submits a
reply.

But this change introduces these side effects:

 - A user will be redirected to another page to see a "Thank you"
   message after submitting a reply.

 - Because of the additional redirection, a user needs to spend slightly
   more time than before.

Resolves: #123
See also: #456, #789

これはあるサイトのコメントフォームで, ユーザがリプライを送信しても何も表示されないので, それだと少し思いやりに欠けるのではないかということで, 感謝を述べるメッセージを表示するようにしたという内容になっています.

より良いコミットメッセージの書き方

そのコミットメッセージを例にどのような点に気をつけるとより良いコミットメッセージを書くことができるかということについて紹介させていただきたいと思います.

Subject の書き方

Subject とはコミットの内容を端的に表すもので, コミットメッセージの一番目の行に書きます.

例の場合ですと次の行になります:

Show a thanks message after a user submits a reply

この Subject を書く上でのポイントを紹介します:

大文字ではじめる

例を見るとわかるように Show... と大文字から始まっています.

英語の文は大文字から始まりますので大文字から始めましょう.

命令形の動詞で始める

Subject は人称 I や We などで始めず, いきなり動詞で始めてしまいましょう.

また動詞も現在進行形や過去形などではなく, 原型のままで, 命令形になるようにします .

例の場合はメッセージを表示すると言うことで Show で始めていますが, 何かを変更するんだったら Change, 更新するんだったら Update, バグの修正だったら Fix, コードを読みやすくするんだったら Refactor とそんな感じにしていきます.

どうして命令形なのかというのは, マージやリバートする時などに Git が自動で生成するコミットメッセージが命令形で始まるというものがあります:

feature ブランチをマージする時:

Merge branch 'feature'

あるコミットをリバートする時:

Revert "<commit-message-subject>"

This reverts commit <full-commit-id>.

つまりはそのような Git が自動で生成するコミットメッセージのフォーマットに倣ってしまったほうが一貫性があっていいよねということです.

ピリオドはつけない

最初の行はメールで言ったら件名なので, ピリオドをつける必要はありません.

ピリオドをつけない分一文字抑えることができるので, そんな小さなメリットもあります .

50 文字以内にする

Subject の文字数はできるだけ 50 文字以内にします.

50 文字を超えても 72 文字以内にするべきです.

あまりに長いと git log コマンドなどでコミットの情報を見るときに見辛くなってしまいます.

なぜ 50 文字以内なのかというのは GitHub でコミットメッセージを書く時にその 50 文字を超える Subject を入力すると警告が出るからというものがあります:

また 50 文字を超えてしまう場合は, 多くても 72 文字以内にするべきというのは GitHub が 72 文字までしか表示しないからでもあります:

またできるだけ 50 文字以内にするというルールを設けることによって, いかに短い文字数でコミットの内容を簡潔に説明することができるかという思考回路を作ることができます.

Twitter のツイートの 128 文字制限のような感じですね.

Body の書き方

Subject はあくまで簡単な説明です.

より詳しい説明は Body の部分に書きましょう.

Body と言うのは, 例の場合だと次の部分になります:

If a user submitted a reply on the comment form, no "Thank you" message
wouldn't be displayed, which lacked a bit of courteousness.

Thus now a "Thank you" message will be displayed if a user submits a
reply.

But this change introduces these side effects:

 - A user will be redirected to another page to see a "Thank you"
   message after submitting a reply.

 - Because of the additional redirection, a user needs to spend slightly
   more time than before.

Resolves: #123
See also: #456, #789

この Body を書く上でのいくつかのポイントを紹介します.

Subject から一行空ける

Body を書くときは例のように, Subject から一行空けて書くようにします.

そうしないと Body として認識されません.

72 文字で改行する

Subject の多くても 72 文字までにするのと同じ要領で, Body の一行一行も 72 文字以内にします.

つまりは 72 文字で改行します.

どうして 72 文字で改行したほうがいいのかというのは Tim Pope さんの A Note About Git Commit Messages という記事に次のように書かれています:

On an 80 column terminal, if we subtract 4 columns for the indent on the left and 4 more for symmetry on the right, we’re left with 72 columns.

80 カラムのターミナルで, もし 4 カラムを左側のインデントとして引き, もう 4 カラムも左右対称にするために右側から引くと 72 カラム残されることになる.

How ではなく What と Why を書く

How というのは追加, 変更したソースコードの内容がどのように動くのかと言うソースコードの意味の説明です.

そのことに関しては既にソースコード自体が説明してくれていますので, 改めて文章化して細々と書く必要はないでしょう.

少し分かりづらいソースコードを説明するという場合は, ソースコードの上部に書くコメントの出番です.

なのでむしろ, その手を加えたソースコードは全体として一体何をするのかという What を書いた方かいいでしょう.

このコミットは要するにこのようなことをするんですといったことです.

例の場合ですと, What は次の部分になります:

Thus now a "Thank you" message will be displayed if a user submits a
reply.

もしユーザがリプライを送信したら感謝を述べるメッセージが表示されるという内容です .

What に加えてどうしてそのような変更をしたのかという Why も書いてあげるとよりコミットの意図が明確になり, 他の人が見たときにこういう理由でコミットしたのねと理解することができるのより良くなります.

例の場合ですと Why は次の部分になります:

If a user submitted a reply on the comment form, no "Thank you" message
wouldn't be displayed, which lacked a bit of courteousness.

ユーザがコメントフォームでリプライを送信したとしても感謝を述べるメッセージは表示されないので, それは少し思いやりに欠けると言う内容です.

このような感じで変更した内容の What と変更した理由の Why を Body に書くことができると後々 git log などで見直した時にそれはどのようなコミットだったかということをすんなり理解することができるのではないでしょうか.

注意点がある場合, そのことも含める

もしコミットが適用されるにあたって注意しておいたほうがいいこと, 注意するべきことがある場合は, それらのことも Body に書いておくとより良いコミットメッセージになります.

例の場合ですと次のものになります:

But this change introduces these side effects:

 - A user will be redirected to another page to see a "Thank you"
   message after submitting a reply.

 - Because of the additional redirection, a user needs to spend slightly
   more time than before.

この変更はこれらの副作用をもたらします:

• ユーザはリプライを送信した後, 感謝を述べるメッセージを見るためにもう一つのページにリダイレクトされます.
• その追加のリダイレクションの為, ユーザは以前に比べて多少多くの時間を要する必要があります.

という内容です.

このような感じで, コミットが適用されることによって引き起こされる副作用がある場合 , そのことも注意点として言及しておくといいのではないでしょうか.

リストの書き方

例の場合, リストは次のものになるのですが:

 - A user will be redirected to another page to see a "Thank you"
   message after submitting a reply.

 - Because of the additional redirection, a user needs to spend slightly
   more time than before.

Body のリストを書く上でのポイントをそれぞれ紹介します.

まず, リストの項目はハイフン - やアスタリスク * で始めます.

そして - の前後には半角スペースを入れ, 項目が複数の行にまたがる時は, 二行目以降の行の先頭を一行目の行の先頭に合わせ, それぞれの項目同士の間は一行空けますが, このような慣習は決まっているわけではありません.

イシューの参照方法

例の場合ですとイシューの参照は次のものになります:

Resolves: #123
See also: #456, #789

そのようにイシューを参照するときは Body の最後に書きます.

GitHub では Resolves: #123 などと書くと, そのコミットがリモートレポジトリのデフォルトのブランチに git push で追加されたり, Pull リクエストでマージされたりすると, そのリモートレポジトリで開いている #123 というイシューが自動的に閉じられます.

ただ自動的にイシューを閉じることができるキーワードというのはあらかじめいくつか決められているので, Resolves の他にどういうキーワードが使えるのかというのは次の URL を参照していただければと思います:

https://help.github.com/articles/closing-issues-using-keywords/

また See also は GitHub ではキーワードとして認識されないので, この場合の #456, #789 というイシューは git push や Pull リクエストでマージされても自動的に閉じられることはありません.

あくまで #123 に関連するイシューとしてメモ的に掲載しているだけです.

まとめ

このような Git のコミットメッセージの書き方は慣習であって, このような慣習に則るとより良いコミットメッセージを書くことができると言うものです.

なので, もしご自身でこのように書いたほうがよりわかりやすいと思われる書き方がある場合は, そのような書き方で書いていただいてもいいのではないかなと思います.

慣習というのは時間の経過とともに少しずつ変化するものですし, チームやプロジェクト内でのルールのようなものがある場合はそちらの方を優先していただければと思います.

なお今回の記事を書くにあたって Chris Beams さんの How to Write a Git Commit Message という素晴らしい記事を参考にさせていただきました.

英語ですが, ご興味のある方はそちらの記事も見ていただけたらと思います.

最後までお読みくださいましてありがとうございました.