【译】编写git commit信息的最佳实践

翻译自：Write good git commit message

写好Git提交信息

很长时间以来，我甚至都不知道编写 git 提交（commit）信息也有它自己的“最佳实践”。在我第一次接触 git 时，提交信息的那部分内容被描述为类似这样的话："...and here you can write something short about what's going on in the commit"。

不好的提交信息

请看下面的提交信息。如果你想合并它们，你真的不会知道哪些是添加的内容，哪些是修改的内容，它们做了什么或者你为什么需要它们。如果你想在历史记录中搜索某些内容，那么上述的糟糕情况同样会遇到。你向下滚动日志，但它仍是一团糟，并且浪费时间。

cd3e27a contact page
aee9d0d comments
eac95e5 list of online users, some other changes because of server
fae5636 little edit
复制代码

好的提交信息

现在再看下这些提交信息。是不是感觉好多了？反正我是这么觉得。

43ec6aa Fix error when the URL is not reachable
4fe84ab Add error message if something went wrong
753aa05 Add server fingerprint check
df3a662 Fix shadow box closing problem
复制代码

如何编写好的提交信息

整个 commit 信息应该有它的格式 - 主题、正文以及可选的由已解决/已关闭的问题组成的结论。

主题

Git 的 commit 帮助页面对提交信息的主题有个很不错的描述：对变更内容进行总结的单行文本（少于50个字符），后跟一个空行。**主题应以大写字母开头且不以句点 . 结尾。**而且重要的是，这必须是一个强制的形式。Chris Beams 为此写了一个简单的规则：

Git 提交信息主题的形式应该总是能够符合这样的句式：如果提交被应用，那么这个提交将“你写的主题”。比如：

【译注】这里可以把“你写的主题”理解成一个动词、一个动作。

• 如果被应用，那么这个提交将删除(Delete)不需要的行。
• 如果被应用，那么这个提交将添加(Add) grep 选项。
• 如果被应用，那么这个提交将修复(Fix)协议缺失时错误。

对于不好的提交信息，就不会符合这个句式：

• 如果被应用，那么这个提交将Contact page。
• 如果被应用，那么这个提交将list of online users, some other changes because of server。

Git 本身就是使用这种方法。当你要合并某些内容时，Git 会生成一个类似这样的提交信息："Merge branch..."，或者回滚时生成 "Revert..."。

正文

在正文里你可以编写哪些内容被修改了以及为什么修改。正文的每一行不应超过72个字符。当然并不是每次提交都需要有正文。

尾行

最后，你可以添加此次 commit 修复的或相关的 issue。它可以是一个链接、数字或者如果你在使用 GitHub，你可以这样写：Resolves #N / Closes #N，这里的 N 表示 issue ID。

示例

这是一个来自我的仓库的提交信息示例：

Fix error when protocol is missing

First, it checks if the protocol is set. If not, it changes the url and
add the basic http protocol on the beginning.
Second, it does a "preflight" request and follows all redirects and
returns the last URL. The process then continues with this URL.

Resolves #17
复制代码

写在最后

感谢你的阅读，希望你从中学到了一些新的东西。如果你有其他的关于如何编写更好的提交消息的提示，或者如何更好地使用此工具，请发表你的评论。

生成变更日志

这样编写提交信息的另一个好处就是很容易生成变更日志。

# show whole commit history
$ git log --oneline --decorate --color

# show history from one tag to another
$ git log 0.0.9..0.0.10 --oneline --decorate --color

# show history form tag to head
git log 0.0.9..HEAD --oneline --decorate --color
复制代码

这种命令的结果就是你的提交列表。

21629ee Fix getResources bug
aa13384 Update docs
44de44c Add HSTS check
复制代码

Commitizen

在 GitHub 上有个名叫 Commitizen 的命令行工具，它可以让提交信息的编写变得更容易。当你想提交的时候，你只需键入 git cz，它会问你一组问题，然后为你创建正确的提交信息。

参考

Git commit manpage

Closing issues using keywords on GitHub

How to Write a Git Commit Message post from Chris Beams

Angular Commit Message Format

转载于:https://juejin.im/post/5c186237f265da613f2f667c