git 提交规范

本文共计4916字，预计预读时间10分钟，包含了约定式提交的提交信息规范和相关工具
给我一个免费的赞吧 (*❦ω❦)👍

约定

式提交-Conventional Commits

  • 意义
    • 统一风格，提高可读性，方便快速浏览查找，回溯之前的工作内容
    • 可以直接从commit生成Chang log （发布新版本时，用于说明和上一个版本差异的文档）
    • 让团队和协作者更好地理解项目的变更历史和版本控制，从而提高代码维护效率和质量。
    • 便于自动化工具（如发布工具或 Changelog 生成器）解析和处理提交记录

官方文档

text 
<类型>[可选 范围]: <描述>

[可选 正文]

[可选 脚注]

三者之间有空行分隔开来

例：

text 
fix(user module): description


Co-authored-by: user1,user2

  • 要求

    • 为了便于阅读，提交信息的任何一行都不能超过 100 个字符

    • 范围：可以是任何能指明变更位置的内容

提交类型

常见的提交类型以及含义如下：

feat: 新功能（feature）
用于提交新功能。
例如：feat: 增加用户注册功能

fix: 修复 bug
用于提交 bug 修复。
例如：fix: 修复登录页面崩溃的问题

docs: 文档变更
用于提交仅文档相关的修改。
例如：docs: 更新README文件

test: 新增或修改测试文件

style: 代码风格变动（不影响代码逻辑）
用于提交格式调整，如标点符号、空格、缩进等；(不影响代码运行的变更)
例如：style: 删除多余的空行

refactor: 代码重构（既不是新增功能也不是修复bug的代码更改）
用于提交代码重构。
例如：refactor: 重构用户验证逻辑

perf: 性能优化
用于提交提升性能的代码修改。
例如：perf: 优化图片加载速度

test: 添加或修改测试
用于提交测试相关的内容。
例如：test: 增加用户模块的单元测试

chore: 杂项（构建过程或辅助工具的变动）
用于提交构建过程、辅助工具等相关的内容修改，一些不更改核心代码的更新
例如：chore: 更新依赖库

build: 构建系统或外部依赖项的变更
用于提交影响构建系统的更改。
例如：build: 升级webpack到版本5

ci: 持续集成配置的变更
用于提交CI配置文件和脚本的修改。
例如：ci: 修改GitHub Actions配置文件

revert: 回滚
用于提交回滚之前的提交。
例如：revert: 回滚feat: 增加用户注册功能

消息体中写明：This reverts commit <hash>，其中<hash>是被还原提交的SHA值

至于开始一个新项目时的提交，你可以写Initial commit

我选择写This is where it all begins...

正文

正文(可选)：对变更的极简描述；并说明代码变动的动机，以及和以前行为的对比

如果是英文：
使用祈使句、现在时：“change” 而非 “changed” 或 “changes”；首字母不要大写；末尾不要加句号

脚注

  1. 格式：

    text 
    键(即令牌): 值

  2. 所有自定义的令牌必须使用连字符 - 连接单词，比如 Co-authored-by (这样有助于 区分脚注和多行正文)。有一种例外情况就是 BREAKING CHANGE，它可以被认为是一个令牌）

  3. 脚注的值可以包含空格和换行

text 
Closes: #123，#124 //本次提交修复或完成了编号为 #123，#124 的 issue
Co-authored-by: user1,user2 //提交的作者
Reviewed-by: zhangsan
BREAKING CHANGE: environment variables now take precedence over config files//破坏性更新

脚注中包含 BREAKING CHANGE: 或 <类型>(范围) 后面有一个 ! 的提交(如，feat!: send an email to the customer when a product is shipped)——
表示引入了破坏性 API 变更（这和语义化版本中的 MAJOR 相对应）。 破坏性变更可以是任意 类型 提交的一部分。

破坏性变更必须在提交信息中标记出来，要么在 <类型>(范围) 前缀中标记，要么作为脚注的一项。
如果使用了 !，那么脚注中可以不写 BREAKING CHANGE:， 同时提交信息的描述中应该用来描述破坏性变更。

相关工具

为了实现规范，我们使用commitlint和husky 来进行提交检查，当执行git commit时会在对应的git钩子上做校验，只有符合格式的Commit message才能提交成功。

为了方便使用，增加了commitizen支持，使用cz-customizable进行配置。支持使用git cz替代git commit。

PS: 之后如果要推行代码规范，也可以使用husky来在其他的Git钩子(如pre-push等)上进行eslint等校验。

Commitizen

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

安装命令如下。

bash 
$ npm install -g commitizen

然后，在项目目录里，运行下面的命令，使其支持 Angular 的 Commit message 格式。

bash 
$ commitizen init cz-conventional-changelog --save --save-exact

以后，凡是用到git commit命令，一律改为使用git cz。这时，就会出现选项，用来生成符合格式的 Commit message。

validate-commit-msg

validate-commit-msg 用于检查 Node 项目的 Commit message 是否符合格式。

它的安装是手动的。首先，拷贝下面这个JS文件，放入你的代码库。文件名可以取为validate-commit-msg.js。

接着，把这个脚本加入 Git 的 hook。下面是在package.json里面使用 ghooks，把这个脚本加为commit-msg时运行。

javascript 
  "config": {
    "ghooks": {
      "commit-msg": "./validate-commit-msg.js"
    }
  }

然后，每次git commit的时候，这个脚本就会自动检查 Commit message 是否合格。如果不合格，就会报错。

bash 
$ git add -A 
$ git commit -m "edit markdown" 
INVALID COMMIT MSG: does not match "<type>(<scope>): <subject>" ! was: edit markdown

生成 Change log

如果你的所有 Commit 都符合格式，那么发布新版本时， Change log 就可以用脚本自动生成（例1，例2，例3）。

生成的文档包括以下三个部分。

  • New features
  • Bug fixes
  • Breaking changes.

每个部分都会罗列相关的 commit ，并且有指向这些 commit 的链接。当然，生成的文档允许手动修改，所以发布前，你还可以添加其他内容。

conventional-changelog 就是生成 Change log 的工具，运行下面的命令即可。

bash 
$ npm install -g conventional-changelog
$ cd my-project
$ conventional-changelog -p angular -i CHANGELOG.md -w

上面命令不会覆盖以前的 Change log，只会在CHANGELOG.md的头部加上自从上次发布以来的变动。

如果你想生成所有发布的 Change log，要改为运行下面的命令。

bash 
$ conventional-changelog -p angular -i CHANGELOG.md -w -r 0

为了方便使用，可以将其写入package.json的scripts字段。

javascript 
{
  "scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -w -r 0"
  }
}

以后，直接运行下面的命令即可。

bash 
$ npm run changelog

参考资料

https://juejin.cn/post/6844903793033756680

https://www.ruanyifeng.com/blog/2016/01/commit_message_change_log.html

https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit

https://blog.csdn.net/chenyajundd/article/details/139322838