カーネルのgitログの質を他のプロジェクトと比べてみるといい、泣きながら眠りにつくことになるだろう。

– Linus Torvalds

あなたのプロジェクトのコミットガイドラインなんて、到底覚えていられない。

プロジェクトごとに求められるものはバラバラだ。

• Conventional Commits
• Problem/Solution形式
• Gitmoji
• 入り組んだ迷宮のようなLinuxカーネルのトレーラー

しかしgit commitテンプレートが役に立つ。コミットテンプレートはコミットメッセージの雛形となり、必要なときに必要な場所、すなわちコミットメッセージを書いているエディタの中でドキュメントを提供してくれる。

git commitテンプレートとは？

git commitと入力すると、gitはテキストエディタを開く¹。gitはエディタをコミットテンプレートであらかじめ埋めておくことができる。記入するフォームのようなものだ。

コミットテンプレートの作成は簡単だ。

• プレーンテキストファイルを作成する――私のものは~/.config/git/message.txtにある
• gitにそれを使うよう伝える：

git config --global \
    commit.template '~/.config/git/message.txt'

私のデフォルトテンプレートには、コミットの書き方について私が知っていることのすべてが詰まっている。

IncludeIfによるプロジェクト固有のテンプレート

コミットテンプレートの本当の妙味は、プロジェクトごとに異なるテンプレートを持てることにある。

gitのincludeIf設定を使えば、プロジェクトごとに異なるテンプレートを使い分けられる²。

Linuxカーネルやgit、MediaWikiといった大規模プロジェクトには、それぞれ独自のコミットガイドラインがある。

Wikimedia関連の作業では、gitリポジトリを~/Projects/Wikimediaにまとめ、グローバルなgit設定（~/.config/git/config）の末尾に次のように記述している：

[includeIf "gitdir:~/Projects/Wikimedia/**"]
    path = ~/.config/git/config.wikimedia

config.wikimediaの中では、Wikimedia専用のコミットテンプレートを指定している。user.emailやcore.hooksPathといった他のgit設定も上書きしている。

例：私のグローバルテンプレート

私のデフォルトのコミットテンプレートは3つのセクションで構成されている：

1. Subject ― 50文字以内、大文字で始め、文末の句読点なし。
2. Body ― 72文字で折り返し、Subjectとは空行で区切る。
3. Trailers ― 標準的なフォーマットで、Bodyとは空行で区切る。

各セクションには、フォーマット³と内容の両方についての指針を加えている。

ヘッダーについては、ガイダンスは簡潔だ：

# 50ch. wide ----------------------------- SUBJECT
#                                                |
#     "If applied, this commit will..."          |
#                                                |
#     Change / Add / Fix                         |
#     Remove / Update / Document                 |
#                                                |
# ------- ↓ LEAVE BLANK LINE ↓ ---------- /SUBJECT

本文については、基本的な問いに答えるよう自分に思い出させる：

# 72ch. wide ------------------------------------------------------ BODY
#                                                                      |
#     - Why should this change be made?                                |
#       - What problem are you solving?                                |
#       - Why this solution?                                           |
#     - What's wrong with the current code?                            |
#     - Are there other ways to do it?                                 |
#     - How can the reviewer confirm it works?                         |
#                                                                      |

あとはgitトレーラーだけだ。

gitトレーラーの入り組んだ迷宮

私のテンプレートには、自分が関わるプロジェクトで使われるトレーラー用のセクションがある。

#     TRAILERS                                                         |
#     --------                                                         |
#     (optional) Uncomment as needed.                                  |
#     Leave a blank line before the trailers.                          |
#                                                                      |
# Bug: #xxxx
# Acked-by: Example User <[email protected]>
# Cc: Example User <[email protected]>
# Co-Authored-by: Example User <[email protected]>
# Requested-by: Example User <[email protected]>
# Reported-by: Example User <[email protected]>
# Reviewed-by: Example User <[email protected]>
# Suggested-by: Example User <[email protected]>
# Tested-by: Example User <[email protected]>
# Thanks: Example User <[email protected]>

これらのトレーラーは、ドキュメントとして役立つ手がかりになる。gitは標準コマンドでこれらを解析できる。

たとえば、コミットと関連タスクをタブ区切りで一覧にしたい場合、git logを使ってBugトレーラーを取得できる：

$ TAB=%x09
$ BUG_TRAILER='%(trailers:key=Bug,valueonly=true,separator=%x2C )'
$ SHORT_HASH=%h
$ SUBJ=%s
$ FORMAT="${SHORT_HASH}${TAB}${BUG_TRAILER}${TAB}${SUBJ}"
$ git log --topo-order --no-merges \
      --format="$FORMAT"
d2b09deb12f     T359762 Rewrite Kurdish (ku) Latin to Arabic converter
28123a6a262     T332865 tests: Remove non-static fallback in HookRunnerTestBase
4e919a307a4     T328919 tests: Remove unused argument from data provider in PageUpdaterTest
bedd0f685f9             objectcache: Improve `RESTBagOStuff::handleError()`
2182a0c4490     T393219 tests: Remove two data provider in RestStructureTest

コミットメッセージのガイドラインを覚えるのはやめよう

git commitテンプレートは、何を書くべきかを覚えておく作業から脳を解放し、伝えるべきストーリーに集中させてくれる。

脳は、得意なことに使おう。