Git
GitHub
GitDay 3

Gitのコミットログ再考

More than 5 years have passed since last update.

始めに

 基本的には、開発はGitで行っています。自分的にはコミットログというのはちゃんと整形しましょう、そうするとあとで何が起きたかトレースするのが楽ですよ、という感じなのですが、意外にもこの辺りについて意識されないようなので、自分の私見を書いておきます。

基本的な情報

 基本的には、Erlang が規則としているコミットログが参考になるでしょう。自分は、Gitを使い始めてから二年間ほど、下のようなコミットログを書いています。

Add: test: foobar.views: ○○のバリデーションチェック

 このような形式に落ち着いた理由として、まずどの類の修正なのか。何かを追加したのか?何かを修正したのか?それともただ消しただけなのかを明確にします。

 そして、そのあとに何処に対して、「追加」あるいは「修正」をしたのか。自分の開発は、基本Webが多いので、だいたい「MVC」か、あるいは「テスト」か、最近だと「ドキュメント」や「レビュー」の類も多いです。

 次に、それが属するモジュール名(自分の場合はPythonなので、上のような形になります)を書きます。そして、具体的に何を修正したのかを書きます。

 このような形式にまとまらない場合、git add -pを使い、上記のようなまとまりになるように、コミットを整えます。

なぜ、コミットログをまとめるべきなのか?

 自分が見てきた範囲ですと、コミットログのまとめられかたを意識されていないプロジェクトというのは、案外あります。なんとなーくGitを導入してみました、というのも流行っているからというわけで、そのコミットログの粒度についてもまちまちだったりします。

 まず理念的なことを言うと、上記のErlangにもある通り、現状のプロジェクトのソースが、どのような経緯で、現在の形になったのかを明確にする役割があります。例えば、自分でもソースリーディングをするさいに、gitkであったり、git logを使ったりします。また、ある行がどのような意図だったのか見たい場合、git blameというものが使えます。このように、ソースの意図というか文脈を残すために、Commit logを適切に書いておくことは、あとあとの手助けになりますし、またコードレビューのレビュアーにとっても、意図が伝わりやすくなるでしょう。

 また、作業的にも、このようなコミットログをまとめている作業をすると、自分が如何なる理由で、そのような作業をしていたのか、あるいはその作業に関して見落としがなかったかをチェックできます。そのように、ミニ振り返りとしても機能を果たします。従って、一人でコードを書いているときであっても、このような作業というのは、十分自分の手助けになったりします。

 ちなみに、gitについては、日本語があやふやになるという問題があるようですが、例えばjoinしているメンバーに海外の人がいるなどの特殊な事情、あるいはオープンソースで書かれているもの、という何かしらの例外がない限り、「意図の表現のしやすさ」ならびに「コードを追いかける人の負荷にならない」ように、日本語を使えばいいのではないか、と思っています。

コミットログが全てではないけどね

 コミットログには色々な流派があると思います。また、この話を知人の技術者にしたところ、「それは細かすぎる。むしろpull requestのフローをちゃんと整えたほうが良い」という意見も頂きました。確かに、上のは神経質すぎる可能性はあります。例えば、HipChatとかIRCでGitHubのログを流していて、それで進捗状況を確認しているとかではない限り、コミットログを整えさせるメリットは無いでしょう。

 ただ、自分としては上記の点で、出来るだけコミットログをまとめると、自分の作業であったり、あるいは何をやっているのか、何をやったのかが明確になっていいなあとは感じますし、そのメリットは十分あると、個人的には思います。