プロジェクトごとの git コミットテンプレート
カーネルの git ログの品質をほかのプロジェクトと比べてみて、泣きながら眠ればいい。
– Linus Torvalds
あなたのプロジェクトのコミットガイドラインなんて、私は絶対に覚えていられません。
プロジェクトごとに、求めるものが違います。
しかし、git のコミットテンプレートが役に立ちます。コミットテンプレートはコミットメッセージの骨組みを用意してくれます。必要な場所、つまりコミットメッセージを書いているエディタの中で、ドキュメントを参照できるのです。
git のコミットテンプレートとは？
git commitを実行すると、git がテキストエディタを開きます1。git はそこにコミットテンプレートをあらかじめ入力できます。記入するフォームのようなものです。
コミットテンプレートの作成は簡単です。
- プレーンテキストファイルを作成します。私の場合は
~/.config/git/message.txtに置いています。 - git に使うよう指示します。
git config --global \
commit.template '~/.config/git/message.txt'私のデフォルトテンプレートには、コミットを書くために知っていることをすべて詰め込んでいます。
IncludeIf でプロジェクト固有のテンプレートを使う
コミットテンプレートの本当の魔法は、プロジェクトごとに異なるテンプレートを使えることです。
git のincludeIf設定を使えば、プロジェクトごとに異なるテンプレートを使えます。2
Linux カーネル、git、MediaWikiのような大規模プロジェクトには、それぞれ独自のコミットガイドラインがあります。
Wikimedia の作業では、git リポジトリを~/Projects/Wikimediaに置いています。グローバル git 設定（~/.config/git/config）の末尾には次のように書いてあります。
[includeIf "gitdir:~/Projects/Wikimedia/**"]
path = ~/.config/git/config.wikimediaconfig.wikimediaでは、Wikimedia 固有のコミットテンプレートを指定しています。user.emailやcore.hooksPathなど、ほかの git 設定も上書きしています。
例：私のグローバルテンプレート
デフォルトのコミットテンプレートには、3 つのセクションがあります。
- 件名：50 文字以内。先頭は大文字にし、末尾には句読点を付けません。
- 本文：72 文字で折り返し、件名との間に空行を入れます。
- トレーラー：標準形式を使い、本文との間に空行を入れます。
各セクションには、形式3と内容の両方について、指針を加えました。
ヘッダーの指針は手短です。
# 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 のコミットテンプレートを使えば、何を書くべきかを覚えておく必要がなくなり、伝えるべきストーリーに集中できます。
脳は、脳が得意なことのために取っておきましょう。