您如何撰写提交信息？

我来写一点跟代码无关的，看似不重要，但在日常编程中却很实用的话题。如何正确书写 git 提交信息？

书写方式没有对错之分；但是，如果项目中每个人的提交信息风格都不一样，那么我们查看提交历史时，会觉得好看吗？更不用说，我们需要毫无规则地通过提交信息来查找和查看前几个月提交中的一些内容了。

消息格式不一致或不遵循任何规则的提交可能会由于多种原因而出现问题：

• 阅读提交消息但不知道提交的具体目的是什么。
• 当我们需要在一段时间的开发后总结源代码的变化（例如生产版本）
• 选择合适的新版本，v1.0.0，v1.0.1，v1.1.0或v2.0.0等。
• 尝试通过正则表达式搜索提交

有些团队决定实施某种封闭规则，以解决代码提交信息样式碎片化带来的一些问题。你可能会问，为什么要封闭？因为这些规则只适用于你的项目。例如，在我的团队中，我们有一个约定，在提交信息和 git 分支前加上工单号。

那么，是否存在一些我们所有人都可以接受的、并且可以在多个项目中共享的规则呢？请输入...

常规提交

约定式提交是一组提交信息书写规则，这些规则易于机器和人类阅读。机器可以利用这些规则，例如在自动版本控制工具中。

这组规则与SemVer（语义版本）相对应，因为它在提交消息中描述了功能、错误修复、代码重构或重大更改。目前，在撰写本文时，这组规则的约定式提交版本为1.0.0-beta.4，并且未来可能会有更多版本。您可以参考 Github 上一些开放项目中约定式提交的实现，其中一些较大的项目包括Electron、IstanbulJs、Yargs和Karma，如果我没有理解错的话，它们实际上为语义提交奠定了基础。

提交信息的结构应如下：

<type>[optional scope]: <description>

[optional body]

[optional footer]

在哪里：

• 和type是description提交消息所必需的，所有其他都是可选的。
• type：关键字来对提交进行分类，如果提交是功能、错误修复、重构...则后跟:。
• scope: 用于对提交进行分类，但回答了以下问题：此提交重构 | 修复了什么？它应紧跟在 后面，用括号括起来，type例如feat(authentication):。fix(parser):
• description：对提交中修改内容的简短描述。
• body：是更长、更详细的描述，当描述无法在一行中写完时，这是必需的：

$ git commit -m "feat: allow the provided config object to extend other configs

BREAKING CHANGE: `extends` key in the config file is now used for extending other config files"

• footer：一些额外信息，例如拉取请求的 ID、贡献者、问题编号……

简短提交信息的一些示例如下：

# ex1: 
$ git commit -m "feat: implement AVOD content reels"

# ex2: 
$ git commit -am "fix: routing issue on the main page"

# ex3 with scope: 
$ git commit -m "fix(player): fix player initialization"

语义版本控制

约定式提交在提交信息中与语义化版本号完全匹配type。自动化版本控制工具也依赖约定式提交来决定源代码的新版本。约定式提交如下：

• fix：(bug)fix 类型的提交在 SemVer 中等于 PATCH。
• feat：feature 类型的提交在 SemVer 中等于 MINOR。
• BREAKING CHANGE此外，提交消息部分中的关键字body将暗示此提交包含修改，使代码不再与先前版本兼容。就像更改 API 的响应结构一样，先前结构中的处理响应部分当然不再准确，现在我们需要通过升级 MAJOR SemVer 版本来创建一个全新的版本。

一些常见type用途包括：

• feat：对用户来说是一个新功能，而不是对构建脚本来说是一个新功能
• fix：为用户修复错误，而不是修复构建脚本
• refactor：重构生产代码
• chore：更新 gulp 任务等；无需更改生产代码
• docs：文档变更
• style：格式、缺少分号等；没有代码更改
• perf：代码在处理性能方面有所改进
• vendor：更新依赖项、包的版本。
• test：添加缺失的测试，重构测试；无需更改生产代码

虽然这些是您在野外看到的最常见的类型，但没有什么可以阻止您创建自己的提交类型。

使用语义提交的另一个额外好处是，你可以从 git 日志中了解你付出的努力。例如，下面给出了 karma（主分支）中一年的 git 提交记录：

$ cd /tmp/karma
$ git log --pretty=oneline --no-merges --since 2017/01/01 --until 2017/12/31 | cut -d " " -f 2 |\
cut -d "(" -f 1 | cut -d ":" -f 1 | sort -r | uniq -c | sort -nr -k1
     39 chore
     28 fix
     23 feat
     15 docs
      6 test
      2 Try
      1 refactor

使用范围注释，我们可以进一步将这些数据细分为诸如哪个组件修复的错误数量最多之类的问题。

概括

• 提交消息必须具有类型（名词形式）的前缀，例如 feat、fix 等，紧接着是范围（如果有）、冒号和空格。```bash

$ git commit -am "测试：添加宣传片中缺失的测试"

- `feat` This type is required to use when adding a feature
- `fix` This type is required to use when fixing a bug
- If there is scope, the scope must be a noun that describes the area of ​​the code change and must be placed immediately after type. Eg, feat(authentication). (Examples?)

```bash


$ git commit -am "refactor(auth): improve refresh token logic"

• 描述必须是对提交中更改的简短描述，并且必须在具有或不具有范围的类型之后。
• 长提交的主体可以紧跟在描述之后，提供更改的背景信息。描述和主体之间必须有一个空行。
• 页脚可以紧跟在正文之后，但正文和页脚之间必须有一个空行。页脚应包含有关提交的扩展信息，例如相关的拉取请求、审阅者、重大更改。每条信息占一行。
• 提交消息中可以使用除feat和之外的其他类型。fix
• 提交重大变更必须在正文或页脚的开头使用大写BREAKING CHANGE关键字指定。后跟冒号、空格和说明。例如：

$ git commit -m "feat(OAuth): add scopes for OAuth apps  

BREAKING CHANGE: environment variables now take precedence over config files."

• !可以在前面添加感叹号type/scope以引起注意并强调提交包含重大更改。

所以现在，在项目使用常规提交后，我们有：

• 人类可读的项目历史
• 努力的测量和分类
• 使用语义发布 (Semantic Release) 自动化版本控制并使用语义发布插件自动为项目生成更改日志的方法。
• 使用 Commit Lint 根据约定提交检查提交消息的方法。
• type当您可以使用正则表达式或 git 工具来按或scope（或两者）过滤提交时，查找、过滤和分析提交历史记录也更加直接。

一些有用的链接

https://www.conventionalcommits.org/en/v1.0.0-beta.4/#specification
https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit
https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional
https://karma-runner.github.io/0.10/dev/git-commit-msg.html
https://electronjs.org/docs/development/pull-requests#commit-message-guidelines
https://chris.beams.io/posts/git-commit/#seven-rules
https://codito.in/semantic-commits-for-git

非常好封面照片由 Yancy Min 拍摄

感谢阅读！