GitHub 项目推荐|Git 提交描述（commit）的编写中文指南
Git 提交描述（commit）的编写指南，中文
在线阅读：https://github.com/RomuloOliveira/commit-messages-guide/blob/master/README_zh-CN.md
项目分析
仓库名称：commit-messages-guide
标星(star)：5658 （很不错的实用项目，大神作品，建议关注）
标星趋势
关注(watch)：91
拷贝(fork)：262
贡献人数：1
仓库大小：<1 MB
代码提交周期分布：
综合推荐指数： 3颗星
项目概述
一个了解 commit 信息重要性和如何更好地编写它的指南。
它可以帮助你了解什么是 commit、为什么编写好的信息很重要、最好的实践案例以及一些技巧来计划和（重新）编写良好的 commit 历史。
什么是“commit”？
简单来讲，commit 就是在本地存储库中编写的文件的 快照。与印象中不同的是，git 不仅存储不同版本文件之间的差异，还存储了所有文件的完整版本。对于两个 commit 之间没有被修改的文件，git 只存储指向前一个完全相同的文件的链接。
下面的图片展示了 git 如何随着时间存储数据，其中每个 “Version” 都是一个 commit：
为什么 commit 信息很重要？
- 加快和简化代码审查（code reviews）
- 帮助理解一个更改
- 解释不能只由代码描述的“为什么”
- 帮助未来的维护人员弄清楚为什么以及如何产生的更改，从而使故障排查和调试更容易
为了最大化这些结果，我们可以使用下一节中描述的一些好的实践和标准。
好的实践
这些是从我的经验、互联网文章和其他指南中整理的一些实践经验。如果你有更多的经验（或持不同意见），请随时提交 Pull Request 提供帮助。
使用祈使句
# Good
Use InventoryBackendPool to retrieve inventory backend
用 InventoryBackendPool 获取库存
# Bad
Used InventoryBackendPool to retrieve inventory backend
InventoryBackendPool 被用于获取库存
不过为什么要使用祈使句呢？
commit 信息描述的是引用的变更部分实际上做了什么，它的效果，而不是因此被做了什么。
Chris Beams 的这篇优秀的文章为我们提供了一些简单的句子，可以帮助我们用祈使句编写更好的 commit 信息：
If applied, this commit will <commit message>
如获许可，此提交将会 <提交备注>
例子：
# Good
If applied, this commit will use InventoryBackendPool to retrieve inventory backend
如获许可，此提交将使用 InventoryBackendPool 获取库存
# Bad
If applied, this commit will used InventoryBackendPool to retrieve inventory backend
如获许可，InventoryBackendPool 将会被用于获取库存
首字母大写
# Good
Add `use` method to Credit model
# Bad
add `use` method to Credit model
首字母大写的原因是遵守英文句子开头使用大写字母的语法规则。
这种做法可能因人而异、因团队而异、甚至因语言而异。不管是否大写，重要的是要制定一个标准并遵守它。
尽量做到只看注释便可明白而无需查看变更内容
# Good
Add `use` method to Credit model
为 Credit 模块添加 `use` 方法
# Bad
Add `use` method
添加 `use` 方法
# Good
Increase left padding between textbox and layout frame
在 textbox 和 layout frame 之间添加向左对齐
# Bad
Adjust css
就改了下 css
它在许多场景中（例如多次 commit、多个更改和重构）非常有用，可以帮助审查人员理解提交者的想法。
使用信息本身来解释“原因”、“目的”、“手段”和其他的细节
# Good
Fix method name of InventoryBackend child classes
Classes derived from InventoryBackend were not
respecting the base class interface.
It worked because the cart was calling the backend implementation
incorrectly.
# Good
Serialize and deserialize credits to json in Cart
Convert the Credit instances to dict for two main reasons:
- Pickle relies on file path for classes and we do not want to break up
everything if a refactor is needed
- Dict and built-in types are pickleable by default
# Good
Add `use` method to Credit
Change from namedtuple to class because we need to
setup a new attribute (in_use_amount) with a new value
信息的主题和正文之间用空行隔开。其他空行被视为信息正文的一部分。
像“-”、“*”和“\\”这样的字符可以提高可读性。
避免使用无上下文的信息
# Bad
Fix this
Fix stuff
It should work now
Change stuff
Adjust css
限制每行字数
这里建议主题最多使用50个字符，正文最多使用72个字符。
保持语言的一致性
对于项目所有者而言：选择一种语言并使用该语言编写所有的 commit 信息。理想情况下，它应与代码注释、默认翻译区域（用于本地化项目）等相匹配。
对于贡献者而言：使用与现有 commit 历史相同的语言编写 commit 信息。
# Good
ababab Add `use` method to Credit model
efefef Use InventoryBackendPool to retrieve inventory backend
bebebe Fix method name of InventoryBackend child classes
# Good (Portuguese example)
ababab Adiciona o método `use` ao model Credit
efefef Usa o InventoryBackendPool para recuperar o backend de estoque
bebebe Corrige nome de método na classe InventoryBackend
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
efefef Add `use` method to Credit model
cdcdcd Agora vai
模板
下面是参考模板，最初由 Tim Pope 编写，出现在 Pro Git Book 中。
用 50 左右或更少的字符描述更改
如有必要，可提供更详细的补充说明，并尽可能将其限定在每行 72 个字符左右。
在某些情况下，第一行被视为 commit 的主题，文本其余部分被作为正文。
因此，将主题从正文分割出来的空白行就显得至关重要(除非完全省略正文)。
如若不然，在使用命令行，如 “log”，“shortlog” 以及 “rebase” 的时候，将会很容易混淆。
解释当前 commit 所解决的问题。
请重点描述产生此更改的原因，而非手段（代码解释了一切）。
是否存在副作用以及其他不直观的影响？
请在这里将其解释清楚。
接下来请另起一行。
- 也可以使用列举要点的格式。
- 通常使用连字符(-)或星号(*)作为要点段落标记，标记与文本之间留一空格，各要点之间留一空行。但这取决于你们的约定。
如果你使用问题跟踪器，请将对它们的引用放在底部，如下所示:
Resolves: #123
See also: #456, #789
Rebase vs. Merge
这部分是 Atlassian 的优秀教程(TL;DR)——"Merging vs. Rebasing" 的精华。
Rebase
TL;DR: 将你的分支逐个应用于基本分支，生成新树。
Merge
TL;DR: 创建一个新的 commit，称为 merge commit（合并提交），其具有两个分支之间的差异。
为什么一些人更喜欢 rebase 而非 merge？
我特别喜欢 rebase 而不是 merge。原因有以下几点：
- 它的历史信息很"干净"，没有无用的合并 commit。
- 所见即所得，即在代码审查中，所有的更改都能在特定的、有标题的 commit 中找到，避免了隐藏在合并 commit 中的修改。
- 通常 merge 是由提交者实行的，并会为每个转换成 commit 的 merge 书写准确的信息。
- 通常我们不会深挖和复查 merge commit，因此尽量避免使用 merge commit，并确保个变化点都有它们所属的 commit 。
什么时候 squash
“Squashing” 是将一系列 commit 压缩成一个的过程。
它在某些情况下很有用，例如：
- 减少那些很少甚至没有上下文（拼写错误、格式化、缺失内容）的 commit
- 将单独的更改连接在一起使它们更通俗易懂
- 重写 work in progress 的 commit
什么时候避免 rebase 或 squash
避免在多人共同开发的公共 commit 或共享分支上使用 rebase 和 squash。rebase 和 squash 会改写历史记录并覆盖当前 commit，在共享分支的 commit（即推送到远程仓库或来自其他分支的 commit）上执行这些操作可能会引起混乱，由于分支产生分歧及冲突，合作者可能会因此失去他们（本地和远程）的更改。
https://github.com/RomuloOliveira/commit-messages-guide
程序员新视界：分享有趣、有料的流行程序员话题，每天进步一点点。