誰にとってもわかりやすいGitのコミットメッセージを考える

yasuda

6年 ago

今ではなくてはならないものになったGitですが、コミットメッセージの書き方に悩んだことがあります。
案件によってルールが違うこともあります。GitHubで有名なリポジトリを見ていても、そのリポジトリの対象範囲や目的などによってルールも違うように感じます。

この記事ではコミットメッセージの役割や、日本語でWebサイトを制作する僕たちはどんなルールにするのが良さそうなのかを考えます。
各ツールによって「課題」「Issue」「チケット」と呼ばれるものは「課題」と表記しています。

また、TAMではプロジェクト管理ツールのBacklogを通してGitのバージョン管理機能を使用しているため、「Gitのコミットメッセージを考える」としていますが、Subversionのような別のバージョン管理システムでも同じように考えることができると思います。

前提となる背景

Gitを使う状況を決めておきましょう。すべての状況で適切なルールを決めるのは難しいからです。

日本語でコミットメッセージを書きます
アプリやサービスではなく、Webサイト（いわゆるホームページ）を対象とします
キャリアの浅い人やGitに慣れていない人も同じように利用します
1つの対応につき1つコミットをします

コミットメッセージには「何を」と「なぜ」を書く

ルールを決める前に、コミットメッセージに書くことと書かないことを決めます。
それはコミットを5W1Hに当てはめてみると明らかになります。

いつ（When）：タイムスタンプで分かる
どこで（Where）：ファイル名とディレクトリで分かる
誰が（Who）：author（作者）で分かる
何を（What）：コミットのタイトル（Subject）とコミットの本文（Body）で分かる
なぜ（Why）：コミットの本文（Body）で分かる
どうやって（How）：コードやdiffで分かる

「何を」と「なぜ」以外はコミットメッセージ以外から読みとることができます。だとしたら、コミットメッセージにはそれらを書く必要はありません。
コミットメッセージには、「何をしたのか？」と「なぜそれをしたのか？」が伝わるようにすればいいことが分かりました。

この記事では、コミットメッセージを主題としているので、コミットの粒度（分割する単位）についてはあまり触れませんが、1つのコミットにつき「何をしたのか」は2つ以上にならないことを前提としています。

コミットメッセージのフォーマット

ここからはコミットメッセージのルールの提案です。

最初にフォーマットを決めます。スペースや改行も含めてルールとします。

<Prefix>: <Subject>

<Body>

<Footer>

コミットメッセージは4つの項目からなります。

Prefix 何をしたかを接頭辞で短くあらわします
Subject 何をしたかを短い文章にします
Body なぜそれをしたのかを文章にします
Footer 補足情報を載せます

以降は4つの項目それぞれのルールを説明します。

Prefix 何をしたのかを英語の動詞にする

英語では「Add」のように動詞から文章を始めることができるので何をしたのかがすぐに分かりますが、日本語では「追加する」から文章を始めると不自然になります。
そのため、日本語のコミットメッセージには、英語の動詞で、そのコミットでどんなことをしたのかを短くあらわします。

動詞	説明
Add:	（機能・ファイルなどを）追加する
Fix:	（コードなどを）修正する
Improve:	（コードなどを）改善する
Update:	（パッケージやドキュメントなどを）更新する
Remove:	（ファイル名やコードを）除去する
Rename:	（ファイル名を）変更する
Move:	（AをBに）移動する
Change:	（AをBに）変更する

英語より漢字のほうが意味を把握しやすいと考えるなら、日本語の動詞に変更してもいいでしょう。

英語	日本語
Add:	追加:
Fix:	修正:
Improve:	改善:
Update:	更新:
Remove:	削除:
Rename:	改名:
Move:	移動:
Change:	交換:

Addは機能やファイルを追加したときに使う

Addは制作の初期段階でよく使うPrefixになります。機能を追加しても、ファイルやパッケージを追加してもAddです。

Fixはコードの修正、Improveはコードの改善に使う

Fixはバグの修正によく使われる印象がありますが、それが修正ならバグでなくてもFixを使います。ドキュメントに対してはタイポ（誤字脱字）以外では使われないようです。

Improveはコードをリファクタリング（パフォーマンスの改善やコードの整形、名前の変更など）をしたときに使います。

Removeは除去、Deleteは削除したときに使う

Removeはファイルを削除したり、コードの一部を取り除いたときに使います。
厳密には、Removeは一部を取り除くといったニュアンスで、完全に消すのはDeleteです。ルールをシンプルにするためにRemoveだけを使うようにしていますが、RemoveとDeleteの両方を使っても構いません。

Subject 何をしたのかを文章にする

Subjectには、そのコミットで何をしたのかを短い文章（タイトル）にします。

◯◯に△△を追加する
文言を修正する
◯◯を最新版にアップデートする

Subjectが長すぎると内容を把握しにくいですし、コミットの粒度が大きすぎる可能性があります。基準として、GitHubで警告になる50文字未満か、省略されてしまう72文字未満に収めます。

Body なぜそれをしたのかを文章にする

Bodyには、追加や修正などが必要だった理由を文章にします。

自己文書化（コメントがなくてもコードの意図が分かる）状態がベストですが、それが難しい場合はコメントをコードに残します。
コードを読むときに、コミットメッセージは探すことはほとんどないはずです。

コミットメッセージにも何をしたのかを残すのもいいでしょう。ただし、コード側でも充分に説明するようにしてください。

Footer 補足情報を残す

Footerには、そのコミットの元になった課題のIDを残します。
例えばBacklogでは、課題のIDをコミットメッセージに残すことで、コミットの情報を課題のページにも登録してくれる機能があります。

該当する課題だけでなく、関連する課題のIDを載せておくのもいいでしょう。

コミットメッセージの用例

フォーマットと4つの項目を踏まえて、どういった使い方をするのか例をあげます。

Add: グローバルナビゲーションを追加する

ファイルは〇〇で管理する。
構成が大きく変わるため、スマホとタブレット以降で別のHTMLを表示している。

#test

「なぜ」は特にないため、Bodyには「注意点」を載せました。

Fix: 表記ルールに従って文言を修正する

表記ルールでは「続きをよむ」は「続きを読む」になっていた。
詳しくは、表記ルールの〇〇を参照。

#test
https://example.com/

Bodyには「なぜ」を、Footerには「参照先」を載せました。

Improve: 画像のファイルサイズを削減する

ファイルサイズが〇〇MBもあり、読み込み時間が遅くなってた。
圧縮ツールに通すことで〇〇MBになり△△%削減した。

#test

Bodyには「なぜ」と「改善結果」を載せました。

Update: npmのパッケージをすべて最新版に更新する

1年前に公開後、更新されていなかった。
改修が始まるため、使用するパッケージやライブラリも新しいバージョンを使うようにする

#test

Bodyには「なぜ」を載せました。

Remove: 使用していない変数を削除する

#test

Subjectだけで説明できているので、Bodyはありません。

Rename: 命名規則に従ってファイル名を変更する

画像ファイル名に大文字が含まれていたため、すべて小文字にしてハイフン区切りにした。
詳しくは、画像のガイドラインの〇〇を参照。

#test
https://example.com/

Bodyには「なぜ」と「したこと」を、Footerには参照先を載せました。

Move: サイト共通の画像として使用するためにアイコンの保存先を変更する

〇〇は△△のカテゴリ以外でも使用することが分かった。
ディレクターと相談し、全体共通のアイコンとして使用することになった。

#test

Bodyには「なぜ」を載せました。

Change: 〇〇のライブラリを△△から□□に変更する

△△には××の機能がなかったため、□□に変更した。
△△は最新更新日が1年以上前だが、□□は1ヶ月前に更新されているのも変更する要因となった。

#test

Bodyには「なぜ」の理由を2つ載せました。

それぞれの案件に応じてルールを変更してください

この記事で説明したルールは、ひとつの例です。
どの案件でも適切かは分かりませんし、もっと厳密にしたり、逆にもっと簡素化したりしてもいいでしょう。

コミットメッセージについて考える機会になったり、ルールを決める助けのひとつになればと思っています。

以下は参考にした記事です。記事中には取り上げなかったコミットメッセージに関する知識もありました。より理解が深まると思いますので、ぜひ読んでみてください。