💌

こんな Git コミットメッセージのテンプレートを設定するといいかも

2023/01/10に公開約2,300字

私が個人的に使っている Git コミットメッセージのテンプレートがこちら。

変更内容のコミットメッセージを入力してください。
'#' で始まる行は無視され、空のメッセージはコミットを中止します。

コミットメッセージは 1 行目に変更内容の概要を記載し、
3 行目以降に変更内容の詳細や、コードで表現できない変更理由を説明してください。

1 行目、すなわちヘッダーはこのソフトウェアの利用者に伝わる形で書いてください。
そのまま CHANGELOG に記載できる形になっていることが望ましいです。
過去形や体言止めではなく現在形で書いてください。
(タグを除いた) 1 行目が次の文に続いたとして自然な形になるのが望ましいです。

もし適用されたら、このコミットは〜

3 行目以降、すなわちボディー部では「なぜ」「なんのために」「どのように」
などを説明してください。特に「なぜ」はコードで表現だけではされないこと多く
後の調査の際に重要な手がかりになります。
「どのように」は無かったとしてもコードを見ることでわかりますが、
素早くコミットの全容を把握するための情報として役立ちます。

コミットメッセージは Conventional Commits のような規約に従って
記述すると自動的な CHANGELOG 作成などに利用できて効果的です。
https://conventionalcommits.org/
https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit

コミットメッセージのフォーマットを次のようにすることを推奨します。

<type>[optional scope]: <description>

[optional body]

[optional footer]

フォーマットの一例です。

feat(parser): 与えられた設定オブジェクトが他の設定を継承することを許可する

BREAKING CHANGE: 現在では設定ファイル中の `extends` キーは
他の設定ファイルを継承するために使われる

また、コミットメッセージ中にはわかりやすさと Semantic Versioning のために
以下のいずれかのタグを記載することを推奨します。上部の記載ほど優先です。

ユーザーに提供する機能に影響のあるもの
  [Header]  feat:               新機能
  [Header]  fix:                不具合修正
  [Footter] BREAKING CHANGE:    互換性のない変更

ユーザーに影響のないアプリケーションコードの変更
  [Header]  perf:               パフォーマンス改善
  [Header]  refactor:           機能追加やバグ修正のないコードの変更
  [Header]  style:              コードの意味に影響のない変更
  [Header]  test:               不足テスト追加もしくは既存テストの修正

アプリケーションコードに関係しない変更
  [Header]  build:              ビルドシステムか外部依存に影響する変更
  [Header]  ci:                 CI 設定の変更
  [Header]  docs:               ドキュメントのみの変更

https://github.com/KoharaKazuya/dotfiles/blob/17610bef860cf957b7219970b1a93dce98dadbfd/.gitmessage より

これを git config の commit.template に設定しており、コミット時に毎回デフォルトのコメントとして表示されるようになっており、いつでも参考にできるようにしています。

このテンプレートは Conventional Commits をベースに、自分にとって必要十分な説明となることを目指して作成しました。

とくに末尾あたりのどのタグを使うかの切り分けは他ではあまり見ない観点で、自分にとってはわかりやすくて気に入っています。ユーザーに影響するかどうか・アプリケーションコードと無関係 (コメントとか外部ツールとか) かどうか。

数年使っていますが、今でもこのスタイルを続けています。自分でいうのもアレですがよくできてると思うのでおすすめです。

こんなことを書いていますが、実際のところ私は Git コミットメッセージのフォーマットに関してはそれほど重要だと思っておらず、十分な説明がされているかどうかが最重要だと考えています (もちろんリポジトリで CHANGELOG の自動生成など、運用ルールがあるならそれに従うべきですが)。スタイルに捉われず、不足なくわかりやすいコミットメッセージを目指したいですね。

Discussion

ログインするとコメントできます