Git Commit Message 最佳实践

0.前言

大咖好呀，我是恋喵大鲤鱼。

Git 是一个免费开源的分布式版本控制系统，由 Linux 之父 Linus Torvalds 于 2005 年开发，最初的目的用于管理 Linux 内核的开发。

因其高效的性能、便捷的分支管理、免费开源等优秀特性，一经推出，很快在全球范围内得到广泛使用，成为最流行的版本控制系统，没有之一。

当我们使用 Git 对代码进行版本管理时，经常需要将变更推送至远端。每次提交变更时，我们需要书写 Commit Message 描述此次变更的内容。

1.Commit Message 是什么？

Git 每次提交代码，都要写 Commit message（提交说明），否则就不允许提交。

git commit -m "hello world"
1

上面代码的 -m 参数，就是用来指定 Commit message 的。

如果一行不够，可以只执行 git commit，就会跳出文本编辑器，让你写多行。

基本上，你写什么都行。但是，一般来说，Commit Message 应该清晰明了，说明本次提交的目的。

下面是来自 Github 的开源项目 Commit Message 示例。

2.Commit Message 的作用？

提交变更时，填写规范的 Commit Message，可以带来诸多好处。

1. 提供更多的历史信息，方便快速浏览。

比如使用下面的命令可以查看上次发布到当前 HEAD（最新提交）之间的提交日志，每个 Commit 占据一行。只看行首，就知道某次 Commit 的目的。

git log <last_release_commit> HEAD --pretty=format:%s
1

last_release_commit 为上次发布的提交的哈希值或分支名。

2. 便于查找关键信息。

可以过滤某些 Commit（比如文档改动），如使用下面的命令仅仅显示新增加的功能。

git log <last_release_commit> HEAD --grep feat
1

3. 可以直接从 Commit 生成 Change Log。

Change Log 是发布新版本时，用来说明与上一个版本差异的文档。规范的 Commit Message 可以使用一些工具和服务（如GitHub、GitLab）自动生成 CHANGELOG 文档。

4. 便于代码审查。

清晰的 Commit Message 可以帮助代码审查者了解提交目的，从而加速 Code Review 过程。

5. 便于问题定位。

良好的 Commit Message 可以帮助开发人员快速定位和理解问题，从而提高代码的可维护性。

6. 项目管理和追踪

规范的提交消息可以帮助项目管理者更好地跟踪开发进度、问题修复情况和特定功能的实现。

7. 提高项目的整体质量，提高个人工程素质。

总之，规范的提交消息不仅是良好的开发实践，还有助于项目的可维护性、协作效率和代码质量的提升。

3.为什么要规范 Commit Message？

如果日常开发中缺少对 Commit Message 的约束，随意填写，会降低 Commit Message 的可读性与作用，随之将会带来一些问题。

请看下面的提交信息。如果你想合并它们，无法得知哪些内容是添加的，哪些是修改的，它们分别做了什么或者你为什么需要这些提交。如果你想在历史记录中搜索某些内容，那么上述糟糕情况同样会遇到。你向下滚动提交历史，乌七八糟，很难找到有用的信息。

cd3e27a contact page
aee9d0d comments
eac95e5 list of online users, some other changes because of server
fae5636 little edit
1
2
3
4

所以规范 Commit Message 在系统开发时显得非常重要，尤其是在多人协作开发大型系统时。

4.用什么规范？

为了让提交消息便于理解，更有意义，我们应该使用规范的格式书写提交信息。

目前社区较流行的方案是 Conventional Commits（约定式提交），它受到了 Angular 提交约定的启发，并在很大程度上以其为依据。

约定式提交是在提交消息之上的轻量级约定。它为创建提交历史提供了一套简单的规则。这使得编写基于规范的自动化工具变得更容易。在提交信息中描述新特性、Bug 修复和破坏性变更，这个约定与 SemVer 相吻合。

约定式提交规定每个提交消息由三个部分组成：Header，Body 和 Footer。

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
1
2
3
4
5

其中，Header 是必需的，Body 和 Footer 可以省略。

4.1 Header

Header 又可细分为类型、范围和描述，其中作用域是可选的。

type

type 表示变更的类型，可以参考 @commitlint/config-conventional 中推荐的 11 个类型。

feat：新增功能（feature）
fix：修复 Bug
docs：用于更新文档、注释或帮助文档。
style：调整代码样式（不影响功能）。如修改命名风格，变量初始化方式等。
refactor：代码重构（不影响功能）。如移动函数位置，拆分代码到不同源码文件等。
test：添加或修改测试代码
ci：与持续集成有关
build：与编译构建相关的变更
revert：恢复之前的提交
perf：性能优化
chore：与特性或 Bug 无关且不修改 Src 或 Test 文件，如构建过程或辅助工具的变更
1
2
3
4
5
6
7
8
9
10
11

注意，以上类型仅是推荐，不是强制限制。除此之外，约定式提交的灵活性也允许你的团队使用自己的类型，并随着时间的推移更改这些类型。

optional scope

optional scope 表示可选的变更范围，可以是文件路径、模块名等。如果变更涉及多个范围，可以使用 “*” 或 “all”。

feat(lang): add polish language
1

注意：如果发生破坏性变更，可以在<type>[optional scope]后面添加一个感叹号 !。

feat(product)!: send an email to the customer when a product is shipped
1

description

description 用于简明扼要地描述修改内容。

4.2 Optional Body

可选的主体是对本次提交的详细描述，可以分成多行。

4.3 Optional Footer

可选的脚注可以用来关联需求或缺陷，比如 JIRA Story 和 Github Issue。

一个关联多个 Issue 完整的 Conventional Commits 提交示例：

fix(api): fix foo to enable bar

This fixes the broken behavior of the component XXX. Before this fix foo wasn't enabled at all, behavior changes from <old> to <new>

Refs: #123, #245, #992
1
2
3
4
5

如果存在不兼容变动，也可以在 Footer 中进行说明，必须以 BREAKING CHANGE 开头，冒号后跟破坏性变更的提交说明。

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files
1
2
3

5.值得关注的一些问题

（1）Header 中的类型应该使用小写还是大写？

大小写都可以，但最好是一致的。

（2）如果提交的变更符合多种类型该如何操作？

回退并尽可能创建多次提交。约定式提交的好处之一是能够促使我们做出更有组织的提交和 PR。

（3）约定式提交和 SemVer 有什么关联呢？

fix 类型提交应当对应到 PATCH 版本。feat 类型提交应该对应到 MINOR 版本。带有 BREAKING CHANGE 的提交不管类型如何，都应该对应到 MAJOR 版本。

（4）约定式提交规范中如何处理还原（revert）提交?

还原提交（Reverting）会比较复杂：你还原的是多个提交吗？如果你还原了一个功能模块，下次发布的应该是补丁吗？

约定式提交不能明确的定义还原行为。所以我们把这个问题留给工具开发者， 基于“类型”和“脚注”的灵活性来开发他们自己的还原处理逻辑。

一种建议是使用 revert 类型，并使用一个页脚来引用正在被恢复的提交哈希值。

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868
1
2
3

6.借助 Commitizen 书写 Commit Message

Commitizen 是一个撰写合格 Commit message 的工具。

借助 Commitizen 提供的 git cz 命令替代我们的 git commit 命令，可以帮助我们书写合格的 Commit Message。

全局安装命令如下：

npm intall -g commitizen
1

安装完 commitizen 后我们还需要为其指定一个适配器（Adapter）。

在 Commitizen 中，不同的项目可能会使用不同的提交消息规范，例如 Angular 的规范、ESLint 的规范等。为了支持这些不同的规范，Commitizen 提供了各种适配器（Adapters），每个适配器都用于将不同的提交消息规范适配到 Commitizen 的格式。

例如使用 cz-conventional-changelog 适配器，使其支持 Angular 的 Commit message 格式。

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

安装完成后，凡是用到 git commit 命令，一律改为使用 git cz。这时，就会以交互的方式，按照一步一步的提示书写符合 Angular 提交约定的 Commit message。

7.小结

除了遵循约定式提交，还可以根据团队或项目的需要制定自己的提交消息规范。重要的是保持一致性，并确保提交消息清晰、有意义，并包含足够的上下文信息。

此外，还可以使用工具和插件来帮助规范化提交消息，如使用 Git 提交模板、提交钩子（Commit Hooks）或自动化提交消息验证工具（Commitlint）等。

无论使用何种规范，编写规范的提交消息都有助于提高代码库的可读性、可维护性和协作效率。

如果您喜欢这篇文章，欢迎关注微信公众号“恋喵大鲤鱼”了解最新精彩内容。

---

参考文献

Conventional Commits
优雅的提交你的Git Commit Message - 稀土掘金