Gitコミットメッセージの表記法と7つのベストプラクティス：「件名と本文の間に空白行を設ける」「本文は72文字で折り返す」

TechTargetは「Gitコミットメッセージの表記法とベストプラクティス」に関する記事を公開した。「件名を50文字以内に制限する」「件名の先頭文字を大文字にする」といった、7つのベストプラクティスを解説する。

[Cameron McKenzie，TechTarget]

印刷

隕九ｋPost

Shareシェア

はてなブックマーク

SharePocket Button

　TechTargetは2024年10月11日（米国時間）、Gitコミットメッセージの書き方に関する記事を公開した。英語での記述法を紹介している。

Gitコミットメッセージの表記法とベストプラクティス（提供：TechTarget）

　Gitコミットメッセージを適切に記述する方法は、何度も取り上げられているトピックだ。

　配属されたばかりのプロジェクトでGitのログにざっと目を通した経験のあるベテラン開発者なら誰でも、Gitコミットメッセージのガイドラインとベストプラクティスについて、開発者に繰り返し注意を与える必要があることを知っている。

Gitコミットメッセージ　7つのベストプラクティス

　Gitコミットメッセージのベストプラクティスとしては、次に挙げる7項目が一般的に受け入れられている。

• 件名を50文字以内に制限する
• 件名の先頭文字を大文字にする
• 件名の末尾にはピリオドを付けない
• 件名と本文の間に空白行を設ける
• 本文は72文字で折り返す
• 命令形を使用する
• 行った内容と理由は記載するがその方法は記載しない

件名を50文字以内に制限する

　Gitの件名を50文字以内に制限する理由は2つある。

　まず、多数のコミットメッセージの中からコミットの目的を探す際、件名が50文字以内であれば素早く見つけることができる。

　次に、文字数を制限することで、開発者が自身の作業を真剣に振り返り、簡潔に表現するよう仕向けられる。開発者がコミットの目的を50文字以内で表現できないとしたら、コミットが不十分、1回のコミットに多くの作業を詰め込み過ぎ、解決すべき問題や作成する機能についての考え方が不十分といった可能性がある。段階的に開発し、頻繁にコミットすれば、コミットは50文字以内で問題なく説明できる。

大文字の使い方に注意する

　書式については、件名の先頭文字は大文字にするが、その他の場所では大文字を不必要に使用しない。コミットログの特定のエントリを検索する際に大文字と小文字を区別するツールを使用する開発者もいる。記述のどこかで「the」の代わりに「The」を使ったことで、検索のプロセスが複雑になり、検索が失敗するような事態は避けたい。

表記ルールに注意する

　新聞の見出しと同様、Gitの件名の末尾にはピリオドを付けない。Gitコミットの本文にはピリオドを使っても構わない。コミット本文の段落は、正しい表記ルールに従う必要がある。

　件名と本文の間には必ず空白行を挿入する。空白行を設けることで、多種多様なGitツールがコミット履歴の書式を効果的に設定できる。簡潔なGit履歴を要求された場合、各コミットの先頭行だけを出力するツールが多い。件名と本文とを分離すると、Gitコミット履歴の操作が容易になる。

72文字の制限に従う

　Gitコミットメッセージを記述する方法のもう一つのルールとして、本文の幅を72文字に制限するというものがある。ただし、これは72文字で折り返すようにテキストエディタを設定すべきという意味ではない。Gitコミットメッセージのこのガイドラインは、コミットメッセージの本文が72文字に近づいたら、必ず改行文字を挿入することを求めている。

　このルールは、Git開発者が使用するツールセットに左右される。GitHubでGitコミット履歴を表示すると、GitHubのUIが行を折り返すため、1行を72文字以内にするという制限は重要ではない。ただし、こうした折り返しがないツールを使うソフトウェア開発者は多い。改行文字を挿入しておかないと、「Emacs」や「vi」を使用する開発者は、Gitコミットの本文を読むのに4～5回右にスクロールすることになる。

Gitコミットメッセージは命令形で記述する

　Gitコミットメッセージの記述は、命令形にするのが一般的に受け入れられているガイドラインだ。つまり、件名に動名詞や過去形は使用しないようにする。

　Gitコミットメッセージの件名は、「～をした」「～をすること」ではなく、「～をせよ」という形で記述する。

• Fixed the fencepost error（fencepostエラーを修正した） //不適切
• Fixing the fencepost error（fencepostエラーを修正すること） //不適切
• Fix the fencepost error（fencepostエラーを修正せよ） //適切

　命令形を使用することは、Gitコミットメッセージのガイドラインの中で開発者が最も違反する傾向にあるガイドラインの一つだ。

操作した内容と理由は記載するがその方法は記載しない

　命令形で記述するのに役立つ優れた経験則がある。それは、次の文章に続けてGitコミットメッセージを記述した場合を想像してみることだ。「If applied, this commit will __（適用すると、このコミットは __だろう）」結果として完成する文章は文法的に正しくなるべきだ。次の3つの例から分かるように、命令形以外の動名詞と過去形は文法として成り立たない。

• If applied, this commit will fixed the fencepost error（適用すると、このコミットはfencepostエラーを修正しただろう）
• If applied, this commit will fixing the fencepost error（適用すると、このコミットはfencepostエラーを修正しているだろう）
• If applied, this commit will fix the fencepost error（適用すると、このコミットはfencepostエラーを修正するだろう）

　このルールには英語文化圏の考え方がある。英語で記載する場合はうまく当てはまるが、当てはまらない言語もある。また、コミットメッセージとして意味を成さなくても、文法的には成り立ち得るエッジケースも確かにある。ただし、一般的には、開発者がGitコミットの件名を記述するときに間違いが起きないようにするためのルールとして受け入れられている。

Gitコミットの本文

　全てのGitコミットに本文が必要なわけではない。説明的な件名だけで十分な場合もあるが、詳細な情報が必要な場合は本文を追加しても構わない。

　コミットメッセージには、チーム内の他の開発者がGitログに素早く目を通して特定のコミットの目的を理解できるよう、操作した内容と理由を簡潔に説明する目的がある。特定の問題をどのように修正したか、または新しい機能を実装するために何を操作したかを細部まで詳しく説明する必要はない。詳しい方法を知りたければ、開発者は実際にコードの違いを調べて実際の変更を確認すればよい。

　ただし、コミットメッセージのフッターは、Atlassianの「Jira」のチケット検索や、当該コミットに関連する他のコミットを追加するのに適している。こうした情報は役立つことが多いが、件名に含めると読みにくくなりがちだ。

　だからといって、適切なGitコミットメッセージを記述する代わりに、手間を省くためにJiraチケットを単に引用するだけというのは避ける必要がある。「Jiraチケット8154を参照」と記述するだけでは、Gitログを調べている開発者に状況が即座に伝わらない。

AngularJSのGitコミットメッセージ表記法

　筆者は、「AngularJS」プロジェクトでコミットメッセージに求められる表記法を、優れたケーススタディーとしていつも提案している。AngularJSでは件名を大文字で始めるというトレンドに逆らい、代わりに各コミットを次の7つの単語のいずれかで始めることを求めている。

• chore（ビルドプロセスや補助ツール、ドキュメント生成などのライブラリに対する変更）
• docs（ドキュメントのみの変更）
• style（コードの意味に影響しない変更）
• feat（新機能）
• fix（バグの修正）
• refactor（バグの修正でも機能の追加でもないコードの変更）
• test（不足するテストの追加や既存のテストの訂正）

　この7つのコミットタイプを付けると、コードベースへの変更を調べる開発者は、ドキュメントのみの更新や、コードの書式を変更するだけのコミットを読み飛ばして、コードベースに影響するコミットに容易に集中できる。

　AngularJSのGitコミットメッセージでは、この7つの単語で始めることに加え、変更したコンポーネントを指定することも推奨されている。この推奨に従えば、開発者は作業中のコンポーネントに影響するリポジトリの変更に簡単に集中できる。

　GitHub上のAngularJSプロジェクトのコミット履歴を見ると、意味のある一貫した表記法によって、多くの開発者が参加する大規模プロジェクトのメンテナンスが大幅に容易になることがすぐに分かる。