2011年1月18日火曜日

【翻訳】Gitのコミットメッセージに関する注意点

Tim Popeさんの "A Note About Git Commit Messages" を翻訳しました。
元記事はこちら: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
(翻訳の公開は本人より許諾済みです)

翻訳の間違い等があればブログコメントやTwitter(@oshow)などで遠慮無くご指摘ください。

Gitのコミットメッセージ
に関する注意点


 良い形式のコミットメッセージを書くということについて、時間を取って説こうと思う。私が考えるに、コミットメッセージ形式に関するベストプラクティスは、Git を素晴らしくしてくれる小さなディティールの一つだ。rails.git への最初のコミットのいくつかは、(折り返しのない)長文による多様なコミットメッセージを含んでおり、なぜこれがはっきり言ってお粗末なプラクティスであるかを詳しく述べたいと思う。

ここにモデルとなるGitのコミットメッセージがある:
Short (50 chars or less) summary of changes

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Write your commit message in the present tense: "Fix bug" and not "Fixed
bug."  This convention matches up with commit messages generated by
commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too

- Typically a hyphen or asterisk is used for the bullet, preceded by a
  single space, with blank lines in between, but conventions vary here

- Use a hanging indent
変更に対する短い(50文字以下の)要約

もし必要なら、より詳しい説明を述べる。約72文字ほどで折り返すようにせよ。
ある文脈では、最初の行はE-Mailの件名になり、残りのテキストが本文になる。
空行で本文と要約を分離するのは絶対に必要だ(本文を省略していない限り)。
もしも二つを繋げてしまうと、rebaseのようなツールが混乱する可能性がある。

現在時制でコミットメッセージを書くこと。"Fixed bug"ではなく"Fix bug"だ。
この慣習は git merge や git revert のようなコマンドが生成したコミット
メッセージと調和する。

さらなる段落があれば空行の後に続けられる。

- 箇条書きも問題ない

- 箇条書きにはハイフンかアスタリスクが使われ、一つスペースを空けてから
  書き始め、合間には空行が入るのが通常だが、この部分の慣習は多種多様だ

- ぶら下げインデント(一行目だけ飛び出して後はインデントする)を使うこと

 コミットメッセージを72文字で折り返すのがなぜ良い事なのかという理由の説明から始めよう。
  • git log はコミットメッセージに対して、なんらの折り返しもしてくれない。デフォルトのページャである less -S では、これは文章が画面外に飛び出してしまうことを意味し、読み辛くなってしまう。横幅80文字のターミナルでは左側のインデントのために4文字引き、右側も釣り合うよう4文字引くなら、残されたのは72文字だ。
  • 訳注: ちなみに、
    $ git config --global core.pager 'less -R'
    とすれば長くても折り返すようになります。もしダメなら以下で。
    $ git config --global core.pager 'LESS=-R less'
    (2014年10月23日追記):Git 2.1.0 からは、デフォルトで折り返しをするようになりました。なので上記のような設定変更は不要です。

  • git format-patch --stdout は一連のコミットをe-mailに変換し、メール本文にコミットメッセージを使用する。良いe-mailネチケットは、横幅80文字のターミナルにおいても溢れないよう、引用表示が何回かネストした時のための余裕を持たせるようにプレーンテキストのe-mailの折り返しを規定している(現在の rails.git のワークフローはe-mailではなく、未来的な何かを組み込んでいるのだろうが)。
Vim ユーザは私の vim-git プラグインをインストールするか、単にGitのコミットメッセージファイルに対して以下のオプションを設定することで、この要件を満たすことができる。
:set textwidth=72
Textmate では、view メニュー下の "Wrap Column" オプションを調節し、^Q を使って文章の折り返しを再適用できる(その後必ず、コメントが混ざるのを避けるために、空行があるか確認すること)。メニューに72文字折り返しを追加するシェルコマンドを以下に用意したので、選択するために何度もドラッグする必要はない。
$ defaults write com.macromates.textmate OakWrapColumns '( 40, 72, 78 )'

 本文の形式を整える方法よりも重要なのが、主題の行をつけるプラクティスだ。例で示したように、あなたは約50文字(これは厳しい限度ではない)を目指すべきだし、とにかく、常にその下に空行を作るべきだ。この最初の行は、そのコミットによって導入された変更への簡潔な要約でなければならない。このような厳しい文字数制限では表現できない技術的な詳細があるならば、代わりに本文の方へ書く。要約の行は Git 全体で使われ、もし長すぎるメッセージだったら端折られてしまうことがしばしばだ。以下はそういった物のうち少数の例を挙げている:
  • git log --pretty=oneline はコミットのハッシュIDと要約を含んだ簡単な履歴を表示する。
  • git rebase --interactive はそれが呼び出すエディタ内で各コミットの要約を提供する。
  • merge.summary オプションが設定されていれば、マージされる全てのコミットの要約が、マージコミットのコミットメッセージ内へ格納される。
  • git shortlog は ChangeLog 的な出力を生成し、その中で要約を使用する。
  • git format-patchgit send-email そして関連するツールは、e-mailの件名として要約を利用する。
  • git reflog によってアクセスできる reflog というローカルな履歴は、馬鹿な間違いからあなたを救ってくれる。そこでは要約の写しが使われる。
  • gitk は要約のためのカラムを持つ。
  • GitHub はそのインターフェース内の様々な場所で要約を利用する。
主題/本文という区別は重要ではないように見えるかもしれないが、それが Git の履歴を Subversion より遥かに快適にしてくれる多くの繊細な要素の一つだ。


0 件のコメント:

コメントを投稿

フォロワー