Git commit と .gitmessage

Git のコミットメッセージの書き方には特に制約もなく、自由に好きなように書けます。しかしながら、伝えたいことが中々うまくまとまらなかったり、適当なコミットばかりしているとのちに履歴が読みにくくなったりします。ある程度の規約を設けると仕事が捗るかもしれません。

Git commit コマンド

お好みのエディターを開いてメッセージを書きたい場合は、オプション指定なしでコマンドを打ちます。

git commit     

Git で使うエディターを指定する方法が複数あるようです。

ターミナル内で完結させたい場合は、-m オプションを用いて直にメッセージを渡す事ができます。

git commit -m "元氣があれば何でもできる" 

複数の段落を設けたい場合は -m オプションを複数回渡す事ができます。それらは1行間隔で連結されます。お好みのエディターで編集する場合も同様に1行空けて複数の段落に分ける事ができます。

git commit -m "概要" -m "本文" -m "脚注"

--cleanup=<mode> オプションがあり、初期設定では # から始まるコメントとメッセージ前後の空白文字が自動で除去されます。通常はこのオプションをいじることはないと思うのですが、この特性は把握しておくと良いと思います。最終的に空になるコミットは（明示的にそれを許可しない限り）無効となります。詳しくは原典をご参照ください。

Git コミットメッセージに規約を設ける

ネット検索してみると、多くの人がコミットの概要に接頭辞をつけることを提案しています。どうもそれらは Angular 関連のプロジェクトで使われている規約が基になっているようです。まずは原典にあたるのが良さそうです。

We have very precise rules over how our Git commit messages must be formatted. This format leads to easier to read commit history.

コミット履歴を読みやすくする目的で、特に Git コミットメッセージの形式については、厳密な規約を設けたとのことです。

構成

1. 概要
2. 空白行
3. 本文
4. 空白行
5. 脚注

概要の書き方

xxx(yyy): zzz
│    │    │
│    │    └─⫸ 現在形での要約（小文字で、最後のピリオドなし）
│    │
│    └─⫸ 影響を受ける範囲、パッケージ等
│  
└─⫸ コミットタイプ

コミットタイプには、Angular チームでは以下のものが使用されています。

• build: ビルドシステムまたは外部依存関係に影響を与える変更
• ci: CI 関連のファイルとスクリプトへの変更
• docs: ドキュメントのみの変更
• feat: 新機能
• fix: バグ修正
• perf: パフォーマンスを向上させるコード変更
• refactor: バグの修正も機能の追加も行わないコード変更
• test: 不足しているテストの追加または既存のテストの修正

いろんな記事を見てみると以下をコミットタイプに含める人もいるようです。

• BREAKING CHANGE: 破壊的変更 (セマンティック バージョニング の メジャーバージョンが上がる時)
• chore: 依存性など
• style: 空白、セミコロン、字下げなど

本文の書き方

• 概要と同様に、現在形で。
• コミットメッセージ変更した動機や理由を説明。
• 変更の影響が把握しやすいよう、以前の動作と新しい動作の対比をここに示してもよい。

脚注の書き方

• 破壊的変更（BREAKING CHANGE）や非推奨（DEPRECATED CHANGE）に関する情報
• 関連する GitHub issues、pull requests、Jira チケットなど

BREAKING CHANGE: <破壊的変更の要約>
<空白行>
<破壊的変更の説明 + 移行手順>
<空白行>
<空白行>
Fixes #<issue 番号>

DEPRECATED: <何が非推奨になるのか>
<空白行>
<非推奨の説明 + アップデート手順>
<空白行>
<空白行>
Closes #<pull-request 番号>

色々参考になります。次のステップとしては適用したい規約をどのように習慣づけるのかという課題が残ります。コミットメッセージを書くたびに規約の書かれた文書を参照するのは面倒だし、記憶するのも大変だと思います。これでは中々習慣にはなりません。解決策の一つとしてGit コミットメッセージのテンプレートがあげられます。

Git コミットメッセージのテンプレートを作る

git commit コマンドを打った時にお気に入りのエディターで表示される内容をカスタマイズする事ができます。そこに適用したい規約や書き方についてのメモする事ができます。やり方は簡単です。

1. ~/.gitmessageを作成し、テンプレートを書く
2. git config --global commit.template ~/.gitmessage コマンドを打ち、上述のテンプレートを登録

例えばこのようなテンプレートを作る事ができます。誰が決めたのか知りませんが、推奨される文字数があるようです。

~/.gitmessage

# ## 概要
# xxx(yyy): zzz
# ------ 50 charcters -------------------------->|


# ## 本文
# ------ 72 charcters ------------------------------------------------>|


# ## 概要の書き方
#
#   xxx(yyy): zzz
#   │    │    │
#   │    │    └─⫸ 現在形での要約（小文字で、最後のピリオドなし）
#   │    │
#   │    └─⫸ 影響を受ける範囲、パッケージ等
#   │
#   └─⫸ コミットの種類
#
# - build: ビルドシステムまたは外部依存関係に影響を与える変更
# - ci: CI 関連のファイルとスクリプトへの変更
# - docs: ドキュメントのみの変更
# - feat: 新機能
# - fix: バグ修正
# - perf: パフォーマンスを向上させるコード変更
# - refactor: バグの修正も機能の追加も行わないコード変更
# - test: 不足しているテストの追加または既存のテストの修正
# - chore: 依存性のアップデートなど
# - style: 空白、セミコロン、字下げなど
#
# ## 本文の書き方
# 
# - 概要と同様に、現在形で。
# - コミットメッセージ変更した動機や理由を説明。
# - 変更の影響が把握しやすいよう、以前の動作と新しい動作の対比をここに示してもよい。
# 
# ## 脚注の書き方
# 
# - 破壊的変更 (BREAKING CHANGE) や非推奨 (DEPRECATED) に関する情報
# - 関連する GitHub issues、pull requests、Jira チケットなど
#
#   BREAKING CHANGE: <破壊的変更の要約>
#   <空白行>
#   <破壊的変更の説明 + 移行手順>
#   <空白行>
#   <空白行>
#   Fixes #<issue 番号>
#
#   DEPRECATED: <何が非推奨になるのか>
#   <空白行>
#   <非推奨の説明 + アップデート手順>
#   <空白行>
#   <空白行>
#   Closes #<pull-request 番号>

コミットのたびに元氣がでるメッセージを表示させて、気持ちを奮い立たせててみても良いかもしれません。# から始まるコメントは除去されるので何でもできます。

# 元氣ですかーーーーッ！ 元氣があればなんでもできる

最強のコミットメッセージを考える

いろんな方が最強の規約を提案してくれています。それらが参考になるかもしれません。あまり深く考えるのは本末転倒の気がしますので、ゆるくやっていけば良いのではないでしょうか。

Qiita で検索しても色々でてきますし、英語の記事も多数見つかります。

できました

commitlint

読者の @RyoWakabayashi さんから 「いつも Conventional Commit を commitlint で強制しています」とお便りをいただきました。ありがとうございます！

モクモク會

本記事は以下のモクモク會での成果です。みなさんから刺激と元氣をいただき、ありがとうございました。

もしご興味のある方はお氣輕にご參加ください。