前言
为了便于团队的协同开发,我们在git commit
时,需要有一个统一的格式。
commit 规范
在业内,一般使用Angular commit message规范。
<type>(<scope>): <subject> // 必填, 描述主要修改类型和内容。注意冒号后面有空格
<BLANK LINE>
<body> // 描述为什么修改, 做了什么样的修改, 以及开发的思路等等
<BLANK LINE>
<footer> // 放 Breaking Changes 或 Closed Issues
- type,必填,
commit
的类型,主要包含下面几种:- feat,新功能
- fix,修复bug
- refactor,重构
- style,格式修改
- docs,文档修改
- build,构建流程或依赖管理等修复
- ci,ci相关的修改
- test,测试用例修改
- perf,性能提升
- revert,回滚
- scope,选填,commit 影响的范围, 比如: route, component, utils, build...
- subject,必填,
commit
的简短描述,格式可以参考50/72 formatting - body,选填,
commit
的具体修改内容, 可以分为多行 - footer,选填,备注信息,通常是Breaking Changes或 Closed Issues
commitlint
我们介绍了commit
的规则,但是需要一个工具来校验是否我们的commit
是否符合该规则,这里我们使用commitlint
来达到这个目的。
下载
npm install -s @commitlint/cli @commitlint/config-angular
@commitlint/config-angular
主要用于生成commit
校验规则,也可以使用@commitlint/config-conventional
(支持type类型为chore
)。
配置文件
在下载完npm包后,我们需要生成配置文件commitlint.config.js
。
echo "module.exports = {extends: ['@commitlint/config-conventional']};" > commitlint.config.js
可以使用上面的命令生成文件,也可以直接创建该文件。
module.exports = {
extends: ['@commitlint/config-angular'],
};
配置规则
@commitlint/config-angular
会自带默认规则,我们也可以通过rules
自己配置符合我们项目的规则。下面是一些常用的配置,项目内容可以看这里。
module.exports = {
extends: ['@commitlint/config-angular'],
rules: {
'type-enum': [ // type的可选类型
2,
'always',
['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore', 'revert'],
],
'type-case': [2, 'always', 'lowerCase'], // type需小写
'type-empty': [2, 'never'], // type不能为空
'subject-full-stop': [2, 'never', '.'], // subject不以‘.’结尾
},
};
rules
中的规则写法为docs/rules。
- 第一个参数(0|1|2),0表示禁止,1表示警告,2表示错误
- 第二个参数(always|never),never表示反转该规则
- 第三个参数,表示用于此规则的值
git hook
作为能用工具就使用工具的原则,我们可以结合git hook来进行commit
的检查。这里我们需要配合husky
来使用。
在husky
已经安装完毕的情况下,我们添加commit-msg
信息。
// package.json
"husky": {
"hooks": {
"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
}
},
这样配置完毕后,在提交commit
的时候就会自己检查commit
规则,若未通过会有类似下面的提示:
ℹ No staged files match any configured task.
husky > commit-msg (node v14.12.0)
⧗ input: chore123: test
✖ type must be one of [feat, fix, docs, style, refactor, test, revert] [type-enum]
上面我们了解了关于commit
的规则以及相关校验,但是我们是否可以往前一步,通过工具来提示或者直接生成commit
呢?
commit 模板
我们通过设置commit
模板,在git commit
时带出模板信息,即可按照规则编辑commit
信息。
首先,在根目录中添加.gitmessage
文件。
# head:
# <type>(<scope>): <subject>
# - type: feat, fix, docs, style, refactor, test, build, ci, revert
# - scope: can be empty (eg. if the change is a global or difficult to assign to a single component)
# - subject: start with verb (such as 'change'), 50-character line
#
# body:
# 72-character wrapped. This should answer:
# * Why was this change necessary?
# * How does it address the problem?
# * Are there any side effects?
#
# footer:
# - Include a link to the ticket, if any.
# - BREAKING CHANGE
#
再添加到git配置中:
// 项目安装
git config commit.template '.gitmessage'
// 全局安装
git config --global commit.template '.gitmessage'
那么,当我们修改了文件,执行了git add
,再执行git commit
(若修改的多个文件,需要执行git add .
和git commit -a
),这时会显示模板信息。
我们仅需要在vim
带出的模板中进行commit
信息编辑,保存后即可正常提交commit
信息。
注:模板中需要提交的commit
信息前不能有#
。
commitizen
除了git commit
模板,我们也可以通过commitizen
来自动生成满足规则的commit
信息。
下载
npm install -s commitizen cz-conventional-changelog
cz-conventional-changelog
是commitizen
的Adapter
,满足Angular团队的commit
规范。
配置
我们在使用npm脚本来控制commitizen
:
// package.json
"script": {
"commit": "cz",
},
接着,需要配置cz-conventional-changelog
。
// package.json
"config": {
"commitizen": {
"path": "cz-conventional-changelog"
}
}
我们也可以在.czrc
或者.cz.json
文件中进行配置cz-conventional-changelog
。
{
"path": "cz-conventional-changelog"
}
命令行
执行命令行npm run commit
,会提示以下信息,按照提示操作即可。
如果全局安装过
commitizen
, 那么可以在对应的项目中执行git cz
$ npm run commit
> cz
cz-cli@4.2.2, cz-conventional-changelog@3.3.0
? Select the type of change that you're committing:
fix: A bug fix
docs: Documentation only changes
style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
❯ refactor: A code change that neither fixes a bug nor adds a feature
perf: A code change that improves performance
test: Adding missing tests or correcting existing tests
build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
自定义 Adapter
当然,我们也可以使用cz-customizable
来自定义Adapter
,用于替换cz-conventional-changelog
。
// 下载
npm i -s cz-customizable
// 配置 package.json
"config": {
"commitizen": {
"path": "node_modules/cz-customizable"
}
}
同时在根目录下创建.cz-config.js
文件, 维护你想要的格式。
PS: cz-customizable
在项目中使用的少,感兴趣的同学可以自行研究。
changelog
我们在有了标准化的commit
基础上,可以通过工具来自动生成changelog。
conventional-changelog
conventional-changelog
能根据项目的commit
和metadata
信息自动生成 changelogs和release notes。
// 下载
npm install -s conventional-changelog-cli
// 配置 package.json
"scripts": {
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0"
}
conventional-changelog
命令行中有多个参数:
- -p angular,表示commit规则标准为angular,现在有angular, atom, codemirror, ember, eslint, express, jquery 等项目的标准
- -i CHANGELOG.md,表示从
CHANGELOG.md
读取changelog - -s 表示读写 changelog 为同一文件
- -r 表示生成 changelog 所需要使用的 release 版本数量,默认为1,全部则是0。
standard-version
standard-version
会根据pacakage.json
中的version
更新版本号,升级版本,打包tag,并更新changelog。
// 下载
npm install --save-dev standard-version
// 配置 package.json
"scripts": {
"release": "standard-version"
}
默认情况下,standard-version
会提升次版本号(minor),我们可以通过参数(可通过standard-version --help
查看全部参数)来控制。
// 当前版本v1.0.0
standard-version // output v1.1.0
// -r 指定版本
standard-version -r major // output v2.0.0
standard-version -r minor // output v1.1.0
standard-version -r patch // output v1.0.1
standard-version -r 3.0.0 // output v3.0.0
// -p 预发版本命名
standard-version -p alpha // output v1.0.0-alpha.0
// -t 版本 tag 前缀
standard-version -t stable- // output tag: stable-v1.0.0
版本说明
以上配置都是在以下版本中:
"@commitlint/cli": "^11.0.0",
"@commitlint/config-angular": "^11.0.0",
"@commitlint/config-conventional": "^11.0.0"
"commitizen": "^4.2.2",
"cz-conventional-changelog": "^3.3.0"
"conventional-changelog-cli": "^2.1.0",
"standard-version": "^9.0.0",
"husky": "^4.3.0",
node -v // v14.12.0
npm -v // 6.14.8