如何写好 commit message

作者: 刘星
日期: 2021年12月27日

现如今,我们的工作基本上离不开版本控制工具了。我们每天都在 commit 代码编写 commit message, 但是你知道如何写出有意义的 commit message 吗。如果你还在写 update codefix bug 这样的信息,那么你很有必要看看本文了。

如果你还不会使用 Git,推荐阅读一篇文章,教你学会 Git

1️⃣ 为什么 commit Message 很重要 🤔 ?

  • 每一个 commit 可以在你的代码库里创建一个个明确的更改节点。
  • 你可以更好地了解代码中的内容是如何被破坏的。
  • 可以让人们看到以前发生过什么,拥有版本历史对于理解代码很重要。
  • 用来证明你的工作,如果你不这样做,那么你注定要在会议上、ticket、报告中一次又一次地重复解释你所做的事情。
  • commit message 在 Code Review 中是十分有意义。

commit message 应该清晰明了,应该明确告诉你的伙伴,你做了什么,为什么这么做。即是他们没有看到 代码,也能理解你所做的事。完全掌握这一点的最佳方法是查看你的项目日志,最好是看看其他人的 commit。看看你能不能理解他们所做的 commit。

2️⃣ 良好的 commit Message 的重要性 🎯

一段时间后,你已经对你之前写代码一脸懵逼了。 当项目出现 Bug 时,commit 历史可以帮助我们快速找出问题究竟出在哪里。 这时你一定希望拥有良好的 commit message,为你提供有关更改内容和原因的有用信息。

但是,如果此时满屏的 update code , fix bug … 你又该从何下手呢?一定是想把写这些信息的人打一顿。

当你在六个月后回顾你自己的提交历史时,试图想起六个月前你写那个 commit 时的想法:

通常来说冗长绝不是一件坏事。事实上,我们鼓励程序员在提交中添加冗长的细节,但仅限于描述中。摘要可以帮助你和其他程序员浏览数千次提交,因此它必须既简洁又富有洞察力。

糟糕的提交信息的例子🤮

是时候对上图的垃圾 commit message 说不了🙅🏻‍♀️!

创建一个好的提交信息一点也不难,我们只需要付出一点点努力然后加以实践。许多开发人员往往有编写糟糕 commit message 的坏习惯。从今天起,我们应该意识到良好 commit message 的重要性。

3️⃣ 10 个 commit 规则 🎯

我想花点时间详细说明什么是格式良好的提交消息。你只需要遵循以下 10 条规则,这将使你的提交信息更清晰,看起来也很舒服,就像下面这样:

每次提交,commit message 都包括三个部分:Header,Body 和 Footer。

<header>
// 空一行
<body>
// 空一行
<footer>

1. 提交消息由 Header (主题)、Body(详细描述) 和 Footer 组成,Body 和 Footer 都是可选的。

2. 将 Header 行 限制为 50 个字符。

  • 主题是最能总结提交中所做更改的一行。
  • 总结提交的行为在任何版本控制系统中都是一种固有的好习惯。它可以帮助其他人(或后来的你)更快地找到相关的提交。

3. 将主题行的第一个字母大写。

4. 不要在主题行的末尾加上句点 (.)。

5. 在 Header 和 Body 以及 Footer 之间放置一个空行。

  • 将 Header 与 Body 分开的空行很重要(除非你完全省略正文)Footer 也应通过空行与正文分开。

6. Body 的行宽不要超过 72 个字符处。

  • Body 用于提供有关 commmit 中所做更改的更多详细信息。

7. 用项目任务号写 commit 的 Body(可选)。

  • 以项目任务号编写时,提交主体看起来很干净。

8. 使用祈使语气

示例:Add 而不是 Added, Fix 而不是 Fixed, Fixes → 主题行使用现在时命令式,正文使用现在时态

9. 描述"什么"和"为什么",但不描述"如何"。

  • 可以提及更改了哪个组件。
  • 只关注目的,而不是实现。
  • 大多数现代错误跟踪和项目管理系统都提供了与源代码控制存储库的集成,但即使它们没有集成,你仍然可以在提交消息放上 task/ticket 编号。

10. 在 Footer 中 包含 ticket 号或者 issue no.(如果有的话)。

  • Footer 位于 Body 正下方,是引用与提交更改相关的问题的地方。如在 GitHub 中的 issue no.,JIRA 中的 ticket 号。

除了上面介绍这 10 个基本 commit message 规则。很多开源项目会在 CONTRIBUTING 中说明它们采用的 commit message 格式,大同小异。

Angular 团队推出的 conventional-changelog 最为有名,使用最广泛。

其格式如下,规定了 type, scope 等。

<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>

笔者几年前写过另一篇 Git 使用文章中有具体介绍,推荐阅读:更优雅的使用 Git

4️⃣ 什么是 50-72 commit 规则?🤔

git log 不会处理换行,因此如果行太长则很难阅读。如果提交的描述一行的长度不限于 72 个字符 那么提交信息将跨越命令行的整个宽度,使 commit message 难以阅读。

以下是当你不限制提交正文长度时,提交消息在 git 中的样子。

以 72 个字符换行文本可防止文本跨越命令行窗口的整个宽度,提高 commit message 的可读性。

注意:如果 commit message 的 Body 超过 72 个字符,Github 会自动将他换行 😳

50/72 规则是一套标准,在行业中得到了很好的认可,是用于标准化提交消息的格式。

50 是 commit message 的 Header 的最大字符数。Body 应该以 72 个字符换行。这两个数字不是随便拍脑袋说出来的任意数字。

对 Linux kernel 中 commit message 的分析表明,50 个字符是提交标题最常见的长度。

数字 72 来自这样一个事实,即 80 个字符是被广泛接受的一行可读字符长度的行业标准,git 会自动在提交消息正文的左侧添加 4 个字符的填充,并且为了保持所有内容居中,在右侧也会填充 4 个字符。

5️⃣ 一些有用的 commit 工具 🔥

前面介绍了一些 commit message 规则,接下来介绍几个工具帮我们更好的将这些在项目中实施落地。

1. committizen

https://github.com/commitizen/cz-cli

是一个撰写合格 commit message 的工具。当你使用 commitizen 提交时,会有个交互式命令行提示你输入 commit message 所有必需的提交字段。

首先全局安装 commitizen

npm install commitizen -g

然后,在项目目录里,运行下面的命令进行初始化,使其支持 Angular 的 commit message 格式。

commitizen init cz-conventional-changelog --save-dev --save-exact

现在,你就可以是用 git cz 来替代 git commit 命令了。

2. commitLint

https://commitlint.js.org/

commitlint 用于帮助你的团队遵守提交约定

安装

npm install -g @commitlint/cli @commitlint/config-conventional

在项目里配置

echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

通常,我们将他与 Git hooks 结合起来使用,实现在 commit 时自动检查 message 是否合法。

husky 是一个十分易用的处理 git hooks 的 npm 包。

https://github.com/typicode/husky

我们只需要进行如下配置就可以开始使用了:

# 安装 Husky v6
npm install husky --save-dev

# 激活 hooks
npx husky install

# 添加 hook
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1'

现在可以输入一个不合法的 message 来进行测试

git commit -m "foo: this will fail"
husky > commit-msg (node v10.1.0)
No staged files match any of provided globs.
⧗   input: foo: this will fail
✖   type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test] [type-enum]

✖   found 1 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

husky > commit-msg hook failed (add --no-verify to bypass)

commitlint 也提供了类似于 commitizen 交互式的命令行工具: @commitlint/prompt-cli。有兴趣的同学也可以自行试试。同时,也可以将 commitlint 与 CI 工具结合使用。

3. gitmoji

https://gitmoji.dev/

最后我们来介绍一个有意思的项目。在 commit message 中使用 emoji

下表是常用 emoji 所代表的含义:

commit TypeEmoji
Initial Commit🎉 Party Popper
Version Tag🔖 Bookmark
New Feature✨ Sparkles
Bugfix🐛 Bug
Security Fix🔒 Lock
Metadata📇 Card Index
Refactoring♻️ Black Universal Recycling Symbol
Documentation📚 Books
Internationalization🌐 Globe With Meridians
Accessibility♿ Wheelchair
Performance🐎 Horse
Cosmetic🎨 Artist Palette
Tooling🔧 Wrench
Tests🚨 Police Cars Revolving Light
Deprecation💩 Pile of Poo
Removal🗑️ Wastebasket
Work In Progress (WIP)🚧 Construction Sign

本文完。

亲爱的读者, 感谢你的时间。我们下期再见! 如果你在评论区留下的想法,我会十分高兴。

文档信息

版权声明:署名-非商业性使用-禁止演绎 4.0 国际(CC BY-NC-ND 4.0)

原文链接:https://www.liuxing.io/blog/how-to-write-a-good-commit/

发表日期:2021年12月27日


相关文章

更优雅的使用 Git

写好 commit message Git 每次提交代码,都要写 Commit message,否则提交不了。我们不光得写 Commit message 而且还应该写的清晰明了,说明本次提交的目的。

2018年5月08日

最近更新