[译]How to Write a Git Commit Message

原文: http://chris.beams.io/posts/git-commit/

 

介绍:为什么好的commit message很重要

你浏览项目commit message的时候或多或少会有些困扰的地方. 例如, 下面是我早前的commit message：

$ git log --oneline -5 --author cbeams --before "Fri Mar 26 2009"

e5f4b49 Re-adding ConfigurationPostProcessorTests after its brief removal in r814. @Ignore-ing the testCglibClassesAreLoadedJustInTimeForEnhancement() method as it turns out this was one of the culprits in the recent build breakage. The classloader hacking causes subtle downstream effects, breaking unrelated tests. The test method is still useful, but should only be run on a manual basis to ensure CGLIB is not prematurely classloaded, and should not be run as part of the automated build.
2db0f12 fixed two build-breaking issues: + reverted ClassMetadataReadingVisitor to revision 794 + eliminated ConfigurationPostProcessorTests until further investigation determines why it causes downstream tests to fail (such as the seemingly unrelated ClassPathXmlApplicationContextTests)
147709f Tweaks to package-info.java files
22b25e0 Consolidated Util and MutableAnnotationUtils classes into existing AsmUtils
7f96f57 polishing

再来看看我最近的commit message:

$ git log --oneline -5 --author pwebb --before "Sat Aug 30 2014"

5ba3db6 Fix failing CompositePropertySourceTests
84564a0 Rework @PropertySource early parsing logic
e142fd1 Add tests for ImportSelector meta-data
887815f Update docbook dependency and generate epub
ac8326d Polish mockito usage

显然第二种更易读一些.第一种长度和形式都不一样, 第二种风格比较统一.

一个好的commit message应该遵循的7条规则

1. 主题和内容用空白行隔开
2. 主题的限制在50个字符内
3. 主题首字母大写
4. 主题结尾不要有标点符号
5. 主题用祈始语句
6. 正文一行最多72个字符
7. 内容里解释做了什么，和为什么这么做

例子:

Summarize changes in around 50 characters or less

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 the commit 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); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequenses of this
change? Here's the place to explain them.

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

If you use an issue tracker, put references to them at the bottom,
like this:

Resolves: #123
See also: #456, #789

1.主题和内容用空白行隔开

来子git commit manapage:

不是必须, 但是最好是用一个简短的行(小于50个字符)作为主题描述这次修改, 然后空一行后写详细的描述. 第一个空白行上面的文字会被git做为标题对待. 

首先, 不是每一个commit message都需要主题和内容. 有的时候一行就行了, 特别是在修改比较简单的情况下.例如:

Fix typo in introduction to user guide

不需要多说什么. 如果实在想看这个拼写是什么, 可以使用git show git diff git log -p.

如果你的committing是上面这种很简单的一个主题就能描述清楚的事情, 使用git commit -m就行了:

$ git commit -m"Fix typo in introduction to user guide"

如果你的committing比较复杂, 需要多点内容进行描述的时候,使用-m就不方便了. 这是你commit的时候不要加-m在弹出来的编辑器里面进行描述会比较好.

主题和内容用空白行隔开是好的. 下面是一个完整的log纪录:

$ git log
commit 42e769bdf4894310333942ffc5a15151222a87be
Author: Kevin Flynn <kevin@flynnsarcade.com>
Date:   Fri Jan 01 00:00:00 1982 -0200

 Derezz the master control program

 MCP turned out to be evil and had become intent on world domination.
 This commit throws Tron's disc into MCP (causing its deresolution)
 and turns it back into a chess game.

使用 git log --oneline, 就只打印出来主题行了:

$ git log --oneline
42e769 Derezz the master control program

使用git shortlog 按作者分组显示的时候也只会打印出主题行:

$ git shortlog
Kevin Flynn (1):
      Derezz the master control program

Alan Bradley (1):
      Introduce security program "Tron"

Ed Dillinger (3):
      Rename chess program to "MCP"
      Modify chess program
      Upgrade chess program

Walter Gibbs (1):
      Introduce protoype chess program

 

2.限制主题在50个字符之内

50个字符不是一个硬性规定. 把主题限制在50个字符之内会让这个主题更易读, 而且还会使得作者尽量用精简的语句来描述发什么了什么.

tip:如果你很难简短的慨括这个修改, 你可能是一次commit了太多的修改了. 要尽量做到一次commit就干一件事情做到原子提交.

GitHub的界面就知道这个约定. 如果你的message超过了50个字符, 他会给你一个警告:

标题超过69这个长度之后的字符会被...:

3.主题首字母大写

主题的首字母大写. 例如:

Accelerate to 88 miles per hour

替代

accelerate to 88 miles per hour

 4.主题的结尾不要有标点符号　　

结尾的标点一点用处都没有, 还会从50个字符里面占掉1个字符.例如:

Open the pod bay doors

替代

open the pod bay doors.

5.主题用祈始语句

祈始语句就像是命令的语句.

• Clean your room
• Close the door
• Take out the trash

祈始语句好像有点粗鲁, 但是它直接明了. 另外merge commit的message也是祈始语句:

Merge branch 'myfeature'

git revert也是祈始语句:

Revert "Add the thing with the stuff"

This reverts commit cc87791524aedd593cff5a74532befe7ab69ce9d.