提交信息指南

漫画作者是Daniel Stori。它遵循知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议。

你的磁盘上有个名为“版本 1”的存档文件应该已经很久了。我猜你肯定用过一些版本控制工具，比如 GitHub、Gitlab、Bitbucket 等等，所以每次想把代码添加到项目时，都必须写提交信息。你有没有想过你的提交信息是否足够好？也许你不喜欢写这些信息，并且想知道为什么每次想推送代码时都要写一遍。毕竟，修改一次还不够吗？

在本文中，我们将讨论编写好的提交消息，而不是好的提交，即使这两个主题紧密相关（这里有一篇来自 Tobias Günther 的好文章，很好地总结了有关版本控制的最佳实践）。

为什么提交信息很重要？

那么，这种改变足够了吗？显然，答案是否定的。但为什么呢？

提交消息用途广泛。这是与项目其他开发人员沟通的首要方式。变更定义了你如何实现某个目标，而提交消息则解释了你这样做的原因。它必须提供足够的上下文，避免开发人员疑惑某些代码为何如此编写。有了恰当的解释，你就不会浪费宝贵的时间去思考开发人员为何推送这段代码。在某些情况下，例如开源项目，如果你不提供一些最低限度的信息，例如精心编写的提交消息，繁忙的维护人员甚至不会阅读你的代码。

提交信息不仅适用于你的同事，也适用于你未来的自己，正如 Peter Hutterer 在这篇关于提交信息的精彩文章中所说的那样。

任何软件项目都是一个协作项目，它至少有两个开发人员，最初的开发人员和几周或几个月后思路早已开走的最初的开发人员。

Peter Hutterer -关于提交信息

项目的设计初衷是长期维护。有时，在一段代码写好几年后，你可能会问自己为什么会这样写。这周我就遇到了一个问题，当时我刚写了一个六个月前才写的函数。写得好的提交信息，更容易让你回到写这个修改时的心情。

管理好提交信息也能简化你的日常生活。一些工具会因为包含有意义的提交历史记录而变得更加有趣，比如一些 git 命令，，，log……当你假期回来时，一个简单的提交信息就能让你了解同事在你休假期间做了什么。编写好的提交信息会迫使你拆分更改，从而更容易使用。rebasecherry-pickgit log --prettygit log -p

说到代码审查，你是否曾经因为开发人员的修改而费力地 rebase 代码？如果提交信息真正有意义，就能更容易地理解修改的原因，让rebase结果更加可预测。另一个例子是git blame命令，顺便说一句，它不是为了取笑你的同事，而是为了提供特定代码行的上下文。当你想重构一段代码时，它会非常有用。

最后但同样重要的一点是，结构良好的提交历史允许在项目的两个版本之间生成变更日志，以告知用户发生了哪些变化。

这有大量理由值得我们花时间去写好的提交信息。

如何写出好的提交信息

既然你已经确信提交信息很重要，那么我们来谈谈如何写出好的提交信息。我从我参与的一个名为immutadot的项目中选取了一些提交信息。正如你所见，这些提交信息并不一致，这使得它们难以阅读。

fix #72 unnecessary object copies
Fixing unshift documentation examples
seq.chain path parameter fix #18
Remove built files
Add tests
Add Circle CI base config
Rename es -> src
Add lang package with toggle, fix exports
Core package

在这些提交信息中，我们可以看到一些在风格、内容和元数据方面的错误。Chris Beams 在他的文章《如何编写 Git 提交信息》中准确地描述了这三点。

风格。标记语法、换行边距、语法、大小写、标点符号。把这些都写清楚，避免猜测，让一切尽可能简洁。最终的结果将是一份高度一致的日志，不仅阅读起来赏心悦目，而且确实会吸引读者定期阅读。

内容。提交消息的主体（如果有）应该包含哪些信息？它不应该包含哪些信息？

元数据。问题跟踪 ID、拉取请求编号等应该如何引用？

Chris Beams -如何编写 Git 提交消息

我们可以看到，只有两个提交的元数据和大写信息……最终，有些信息内容太少，我们甚至无法理解提交的具体含义。在同一篇文章中，Chris 介绍了编写良好提交信息的 7 条规则：

1. 用空行分隔主题和正文
2. 将主题行限制为 50 个字符
3. 主题行大写
4. 不要以句号结尾
5. 在主题行中使用祈使语气
6. 正文在 72 个字符处换行
7. 使用正文来解释什么、为什么以及如何

Chris Beams -如何编写 Git 提交消息

我个人应用了以下规则的一部分：

• 将主题行限制为 50 个字符
• 主题行大写
• 在主题行中使用祈使语气

字符限制不仅迫使你简洁，这是一项很棒的技能，而且它与许多工具非常契合，正如 Tim Pope 的文章《关于 Git 提交消息的说明》中解释的那样。

我倾向于认为完美是优秀的敌人。这就是为什么我省略了关于提交消息正文的内容。我认为我们在摘要部分已经有足够的工作要做了。但我还是想补充一条规则作为补充：

• 添加拉取请求/合并请求跟踪 ID

大多数情况下，我们会使用 GitHub、GitLab 等工具在代码审查过程中进行讨论。所有关于变更的信息至少都会在这些工具上描述。我添加了这条关于跟踪 ID 的规则，以便轻松找到相关的拉取/合并请求。编写提交主体比添加跟踪 ID 更好，因为如果您更改了存储库管理器解决方案，您将丢失所有这些宝贵的上下文信息，并且您的跟踪 ID 将毫无用处。

这是我参与的名为gitmoji-changelog的项目中的一个较新的例子，它遵循以下规则：

Make core independent from the git client (#171)
Upgrade Docker image version (#167)
Add maven preset (#172)
Add a generic preset using configuration file (#160)
Improve error messages for preset system (#161)
Publish Canary version on master push (#141)

拥有一致的风格会让代码更易于阅读。您可以了解变更的上下文，并且元数据可以直接访问。最重要的是在团队中找到共同的规则，以确保拥有结构良好的提交历史。有一些约定可以帮助您找到这些规则，但我们稍后会再讨论这个主题。

如果你不知道该写什么信息，或许应该将你的提交拆分成更小的部分。Peter Hutterer 在他的文章《关于提交信息》中列举了一些难以找到良好提交信息的例子，因为你的提交补丁可能缺乏逻辑性。

奖金

如果您使用结对或群体编程等实践，请不要忘记在提交消息中添加同事的姓名：

$ git commit -m "Refactor usability tests.
>
>
Co-authored-by: name <name@example.com>
Co-authored-by: another-name <another-name@example.com>"

提交约定

正如上一节所述，您应该为您的团队定义一个提交约定。现有的开源提交约定可以为您提供一些灵感。它们还拥有一个完整的生态系统，其中包含一些工具，可以帮助您编写提交消息、生成变更日志、创建版本等等。很多事情可能需要花费大量时间。它们都有完善的文档，因此您无需自行编写关于提交消息约定的文档。

我们将讨论其中两个：Conventional Commits和gitmoji。

常规提交

该规范的灵感来源于Angular 提交消息指南。它包含一些有趣的规则，例如：

• 提交必须以类型为前缀（feat、fix）
• 可以提供一个范围来指出代码库的特定部分（对于 monorepos 来说真的很有趣）
• 重大变更必须包含在页脚部分

使用此规范，提交消息的结构如下：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

请参阅其规格部分以了解更多信息。

吉特莫吉

我很喜欢 Gitmoji 提交约定。它使用表情符号对提交进行分类。我是一个视觉型的人，所以它很适合我，但我明白这个约定并不适合所有人。

我之前在gitmoji-changelog的提交示例中并没有完全诚实。你现在应该已经猜到了，其中有一个部分缺失了。

:recycle: Make core independent from the git client (#171)
:whale: Upgrade Docker image version (#167)
:sparkles: Add maven preset (#172)
:sparkles: Add a generic preset using configuration file (#160)
:recycle: Improve error messages for preset system (#161)
:construction_worker: Publish Canary version on master push (#141)

这些文本别名广泛用于 Slack、Discord 等工具。大多数存储库管理器工具（如 GitHub 或 GitLab）都会解释它们并在其 UI 中很好地显示它们：

♻️ Make core independent from the git client (#171)
🐳 Upgrade Docker image version (#167)
✨ Add maven preset (#172)
✨ Add a generic preset using configuration file (#160)
♻️ Improve error messages for preset system (#161)
👷‍♂️ Publish Canary version on master push (#141)

我喜欢这个惯例，因为我一眼就能看出提交会带来什么样的变化。它自带了一个名为gitmoji-cli的命令行工具，可以帮助你编写提交信息，我还为它制作了一个变更日志生成器。

还有更多。请记住，这些只是指导原则，您可以混合使用它们来满足您的需求。例如，如果您在 Monorepo 上工作，可以使用 gitmoji 约定和常规提交的范围概念。

欢迎反馈🙏如果您有任何问题，请发推文给我@YvonnickFrin！