第四篇-添加工具规范 git commit message

vue►vue3项目 , 评论

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

一般来说，commit message 应该清晰明了，说明本次提交的目的，是新增了一个功能或者修复了一个bug 之类的，但是随着项目组人员增多，仅靠口头的约束有时候还是会出错的，所以我们需要通过工具来帮助规范团队的 commit message。

规范的 commit message

每次提交，Commit message 都包括三个部分：Header，Body 和 Footer。

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

不管是哪一个部分，任何一行都不得超过72个字符（或100个字符）。这是为了避免自动换行影响美观。

1
2
3
4
5
<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>

Header部分只有一行，包括三个字段：type（必需）、scope（可选）和 subject（必需）。

type

type用于说明 commit 的类别，可以使用以下标识

1
2
3
4
5
6
7
8
9
10
11
feat：新功能（feature）
fix：修补bug
docs：文档（documentation）
style： 格式（不影响代码运行的变动）
refactor：重构（即不是新增功能，也不是修改bug的代码变动）
perf：优化相关，比如提升性能、体验
test：增加测试
build：构建
ci：更改ci configuration
chore：构建过程或辅助工具的变动
revert：撤销commit/回滚版本

如果 type 为 feat 和 fix，则该 commit 将肯定出现在 Change log 之中。其他情况默认不加入，可以修改，建议不要。

scope

scope用于说明 commit 影响的范围，比如数据层、控制层、视图层等等，视项目不同而不同。

subject

subject是 commit 目的的简短描述，不超过50个字符。有以下限制

1
2
3
以动词开头，使用第一人称现在时，比如change，而不是changed或changes
第一个字母小写
结尾不加句号（.）

Body

Body 部分是对本次 commit 的详细描述，可以分成多行。使用 git commit 会弹出多行编辑器

有两个注意点。

  1. 使用第一人称现在时，比如使用 change而不是 changed或 changes。
  2. 应该说明代码变动的动机，以及与以前行为的对比。

Footer 部分只用于两种情况。

不兼容变动

如果当前代码与上一个版本不兼容，则 Footer 部分以 BREAKING CHANGE开头，后面是对变动的描述、以及变动理由和迁移方法。

关闭 Issue

如果当前 commit 针对某个issue，那么可以在 Footer 部分关闭这个 issue 。

1
2
3
fix #1
# 关闭多个
fix #1, #2

validate-commit-msg

validate-commit-msg 是什么?

一个可以校验 commit message 的二进制文件

安装 validate-commit-msg
1
2
3
npm install validate-commit-msg --save-dev
#or
yarn add validate-commit-msg --dev

validate-commit-msg 的配置可以通过项目根目录下的 .vcmrc 文件，或者在 package.json 中修改

.vcmrc 文件内容是一个正确的 json 格式

validate-commit-msg 提供了默认配置，一般项目开发不需要修改这个

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "types": ["feat", "fix", "docs", "style", "refactor", "perf", "test", "build", "ci", "chore", "revert"],
  "scope": {
    "required": false,
    "allowed": ["*"],
    "validate": false,
    "multiple": false
  },
  "warnOnFail": false,
  "maxSubjectLength": 100,
  "subjectPattern": ".+",
  "subjectPatternErrorMsg": "subject does not match subject pattern!",
  "helpMessage": "",
  "autoFix": false
}

在 package.json 中修改配置

1
2
3
4
5
6
7
{
  "config": {
    "validate-commit-msg": {
      /* 这里写配置的参数 */
    }
  }
}

.vcmrc 文件的优先级更高，如果 .vcmrc 文件不存在，才会从 package.json 中读取

husky

husky是什么？

husky 是一个 Git Hook 工具。husky 其实就是一个为 git 客户端增加 hook 的工具。将其安装到所在仓库的过程中它会自动在 .git/ 目录下增加相应的钩子实现在 pre-commit阶段就执行一系列流程保证每一个 commit 的正确性。

安装 husky

不同的包管理工具使用不一样的安装方法：官方文档

1
2
3
npx husky-init && npm install       # npm
npx husky-init && yarn              # Yarn 1
yarn dlx husky-init --yarn2 && yarn # Yarn 2

执行之后会在项目根目录生成 .husky 目录，目录下会有一个 pre-commit 文件，把文件中的 npm test 修改为 npm run lint，如果你的项目中没有使用 eslint，可以把这个文件直接改名成 commit-msg，把文件中的 npm test 修改为 npx validate-commit-msg。

将 pre-commit 文件复制两份命名为 commit-msg 和 pre-push

commit-msg 文件中的 npm run lint 修改为 npx validate-commit-msg

pre-push 文件中的 npm run lint 修改为 npm run test:unit，如果你的项目没有使用单元测试可以不需要这个文件

  • pre-commit 会在输入提交信息之前调用，校验 eslint
  • commit-msg 输入了提交信息，如果校验出错，放弃提交
  • pre-push git push 执行的时候 更新了远程引用但尚未推送到远程时被调用

测试一下 validate-commit-msg 和 husky 是否生效

回到项目根目录下执行

1
2
git add .
git commit -m "随便提交点"

出现以下信息代表 commit-msg 钩子中执行的 validate-commit-msg 生效了

1
2
3
AINVALID COMMIT MSG: does not match "<type>(<scope>): <subject>" !
随便提交点
husky - commit-msg hook exited with code 1 (error)

做一次正确的提交，commit msg 应该必须包含 type : 和 subject，scope 是可选的

1
2
git commit -m "chore: 添加husky和validate-commit-msg校验commit msg"
git push

image-20210908164353225

image-20210908164322923

Commitizen

Commitizen 是什么?

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

安装 Commitizen
1
2
3
npm install commitizen --save-dev
#or
yarn add commitizen --dev

初始化项目中使用 cz-conventional-changelog 适配器

1
2
3
4
# npm 包管理工具执行
npx commitizen init cz-conventional-changelog --save-dev --save-exact
# yarn 包管理工具执行
npx commitizen init cz-conventional-changelog --yarn --dev --exact

package.json 文件中会自动添加 commitizen 配置

1
2
3
4
5
"config": {
  "commitizen": {
    "path": "./node_modules/cz-conventional-changelog"
  }
}

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

测试一下

1
2
git add .
npx cz

image-20210908172549706

使用 git log 可以查看刚才的 commit message

image-20210908172658898

还可以在 package.json 中添加更加方便的执行命令，在 package.json 的 scripts 中添加

1
2
"cz": "cz",
"commit": "git add . && cz"

之后在提交代码，就可以在项目根目录下执行

1
2
3
npm run commit
# or
yarn commit

生成 changelog

如果项目中所有的 commit 都是按照上述格式提交的，那么 change log，就可以用脚本自动生成。

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

1
2
3
New features
Bug fixes
Breaking changes

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

conventional-changelog 就是生成 Change log 的工具

安装 conventional-changelog
1
2
3
npm install conventional-changelog-cli --save-dev
# or
yarn add conventional-changelog-cli --dev

命令行执行以下命令就会在项目根目录下生成 CHANGELOG.md

1
npx conventional-changelog -p angular -i CHANGELOG.md -s

image-20210908174527422

之后在发布新的版本的时候都可以使用这个命令，往 CHANGELOG.md 文件中，添加新版本的log

可以把这个命令添加到 package.json 中的 scripts 下，方便之后的使用

1
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"

之后就可以使用以下命令往 CHANGELOG.md 文件中，添加新版本的log

1
2
3
npm run changelog
# or 
yarn changelog

相关资料

阮一峰 Commit message 和 Change log 编写指南

完结

项目已经上传到 github 和 gitee

GitHub: https://github.com/wukang0718/cli-create-project

Gitee: https://gitee.com/wu_kang0718/cli-create-project

下一篇：集成axios

武康前端开发

一个做前端开发的小学生