如何写好Git commit log?

介绍: 为什么好的提交信息如此重要如果你对如何写好 git 提交信息没有仔细想过，那你很可能没有怎么使用过 git log 和相关工具。这里有一个恶性循环：因为提交的历史信息组织混乱而且前后矛盾，那后面的人也就不愿意花时间去使用和维护它。 又因为没有人去使用和维护它，提交的信息就会一直组织混乱和前后矛盾。但一个好的日志是一个优美和有用的东西，一旦日志处理的好，那么git blame、revert、rebase、log、shortlog 和其它子命令都将发挥它们的作用。查看别人的提交和 pull 请求是值得的，而且可以随时独立完成。理解几个月或者几年前发生的代码变动不仅变得可能，而且高效。一个项目的长期成功依赖于（除了其它方面）它的可维护性，一个维护者最有力的工具就是项目的日志。所以非常值得花时间学习如何正确地维护它。刚开始可能很麻烦，但很快会成为习惯，最终会成为人们自豪和生产力的源泉。我在这篇文章只会讨论如何保持一个健康的提交历史的最基本要素：即如何写好个人的提交信息。其它重要的实践，比如 commit squashing，我在这里不会涉及。我可能会在后续文章里讨论这些。对于什么是惯用的约定，即命名和格式等，大多数编程语言都已经形成惯例。这些约定千差万别，但是大多数开发者都同意选择一种并坚持下去，这比让每个人自行其事导致混乱要好得多。一个团队提交日志的方法应该一致 。为了创建一个有用的修改历史，团队应该首先对提交信息的约定形成共识，至少明确以下三件事情：风格。包含句语、自动换行间距、文法、大小写、拼写。把这些讲清楚，不要让大家猜，并尽可能保持简单。最终的结果就是一份相当一致的日志，不仅让人读起来很爽，而且可以定期阅读。内容。哪些信息应该包含在提交信息（如果有）的正文中？哪些不用？元数据。如何引用问题跟踪 ID，pull 请求编号等？幸运地是，如何生成一个地道的 git 提交信息已经有完善的约定。事实上，大部分都集成在 git 命令中，你不需要重新发明什么。你只需要遵循如下七条规则，就可以像老手一样提交日志。七条很棒的 git 提交信息规则1. 用一个空行隔开标题和正文2. 限制标题字数在 50 个字符内3. 用大写字母写标题行4. 不要用句号结束标题行5. 在标题行使用祈使语气6. 正文在 72 个字符处换行7. 使用正文解释是什么和为什么，而不是如何做1. 用一个空行隔开标题和正文首先，不是每一个提交都需要标题和正文。有时简单一行也可以，特别是当这个改动很简单将来也不会变化。不需要再多说什么了。如果读者想知道拼写错误具体是什么，她通过 git show，git diff 或者 git log -p 命令，就可以很容易地看到这个改动。git 中标题和正文之间的差别还体现在许多其他的功能上，但前提是标题和正文之间要有空行，这才能正常工作。2. 限制标题字数在50个字符内50个字符不是一个硬性规定，只是一个经验之谈。把标题行限制在这个长度，既保证它们容易阅读，也强迫作者去思考如何用最精简的方式解释发生了什么。小技巧：如果你发现很难总结，那你可能一次提交太多改动了。 争取作原子的提交（一个题目对应一个单独的提交）GitHub 的界面充分考虑到这些约定。如果超过50个字符的限制，它会警告你：3. 用大写字母写标题行这个很简单。标题行的首字母大写。4. 不要用句号结束标题行标题行不需要考虑标点符号。而且如果希望保持在 50 个字符以内，慎用空格。5. 在标题行使用祈使语气祈使语气就是像给一个命令或指示一样叙述或写作。一些例子如下：· 打扫你的房间· 关门· 倒垃圾你现在读到七个原则中的每一个都是用祈使语气书写的。（“正文在 72 个字符处换行”等）祈使语气听起来有点粗鲁；所以我们通常不使用它。但对 git 提交信息的标题行而言，它确实很棒。一个原因是当 git 代表你创建一个提交时，它自己就是使用祈使语气。当你用祈使语气编写你的提交信息时，你遵守了 git 内在的约定。例如：· 重构 X 子系统以增加可读性· 更新新手入门的文档· 删除弃用的方法· 发布1.0.0版本一开始这样写会有点尴尬。同样是用来描述事实，我们更习惯用陈述方式去讲话。这也就是为什么提交信息常常读起来都是这样：· 用 Y 修正了问题· X的改变行为有时编写的提交信息像是一个内容的描述：· 对损坏事物的更多修正· 新酷的 API 方法有一个简单的规则，每次把它做正确就可以减少误解。一个格式正确的 git 标题行应该可以完成下面的句子：如果被采用，这个 commit 将把你的标题放在这里例如：· 如果被采用，这个 commit 将会重构 X 子系统以增加可读性· 如果被采用，这个 commit 将会更新新手入门的文档· 如果被采用，这个 commit 将移出弃用的方法· 如果被采用，这个 commit 将发布 1.0.0 版本· 如果被采用，这个 commit 将从 user/branch 合并 #123 pull 请求注意下面这些非祈使格式不能工作：· 如果被采用，这个 commit 将用 Y 修正了问题· 如果被采用，这个 commit 将X 的改变行为· 如果被采用，这个 commit 将对损坏事物的更多修正· 如果被采用，这个 commit 将新酷的 API 方法记住：使用祈使语气只在标题上是重要的。你在编写正文的时候，可以放宽这一限制。6. 正文在72个字符处换行Git 从来不自动换行。当你编写一个提交信息的正文时，你必须考虑到正确的间距和手动换行。推荐在72个字符处换行，这样 git 有足够的空间来缩进文本，还可以保持整体都在80个字符以内。一个好的编辑器在这里可以有所帮助。例如当你编写一个 git 提交时，可以很容易在 Vim 上设定 72 个字符换行。但是通常，IDE 提供文本换行的智能支持都很糟糕（虽然在最近版本中，IntelliJ IDEA终于有所改善）。7. 使用正文解释是什么和为什么，而不是如何做这个提交是一个来自 Bittcoin Core 的好例子，解释了什么被改动了和为什么：看一下完整的 diff，可以想象作者当下花了多少时间提供这些上下文信息，这大大节省了同伴和未来提交者的时间。如果他不这么做，这些信息可能就永远消失了。大多数情况下，你可以省去改动的具体实现细节。 在这点上，代码通常是不需加以说明的（如果代码太复杂需要文字解释，可以使用代码注释）。首先把你做这个改动的原因交待清楚 —— 改动前是如何工作的（和出了什么问题），现在是如何工作的，以及为什么你要采用这种方法解决问题。小技巧学着去热爱命令行。抛弃 IDE。拥抱命令行是明智的，理由就像 git 子命令那样多。Git 是强大的，IDE 也是，但是表现的方式不同。我每天都使用 IDE （IntelliJ IDEA），也用过不少其它的IDE（Eclipse），但我看到集成 git 的IDE ，都无法企及命令行的方便和强大（一旦你了解它）。某些 git 相关的 IDE 功能是很有用的，比如通过调用git rm 删除一个文件，用 git 重新命名一个文件。但一旦你开始使用 commit、merge、rebase 这些命令，或者进行复杂的历史分析，IDE 就无能为力了。要发挥 git 的全部火力，那就是命令行。记住无论你使用 Bash 还是 Z shell，都可以使用 Tab 补齐脚本来减轻记住子命令和开关的痛苦。