前言
我在平时使用 git 时,都是随意编写提交说明。发现问题时进行版本回退,看着杂乱无章的提交说明,根本搞不清哪一次提交了什么内容,深受其害。
之后在学习过程中,认识到 Commit 规范与配置,总结内容,分享出来。
什么是 Commit message
Git 每次提交代码,都要写 Commit message(提交说明),否则就不允许提交。
git commit -m "hello world"
上面代码的 -m
参数,就是用来指定 Commit message 的。
如果一行不够,可以只执行 git commit
,就会跳出文本编辑器,让你写多行。
基本上,你写什么都行。但是,一般来说,Commit message 应该清晰明了,说明本次提交的目的。
目前,社区有多种 Commit message 的 写法规范。本文介绍 Angular 规范(见上图),这是目前使用最广的写法,比较合理和系统化,并且有配套的工具。
Commit message 的作用
格式化的 Commit message,有几个好处。
(1)提供更多的历史信息,方便快速浏览。
比如,下面的命令显示上次发布后的变动,每个 commit 占据一行。你只看行首,就知道某次 commit 的目的。
git log --oneline
(2)可以过滤某些 Commit(比如文档改动),便于快速查找信息。
比如,下面的命令仅仅显示本次发布新增加的功能。
git log --grep feature
(3)可以直接从 Commit 生成 Change log。
Change Log 是发布新版本时,用来说明与上一个版本差异的文档,详见后文。
Commit message 格式
每次提交,commit message 都包括三个部分:Header,Body 和 Footer。其中,Header 是必需的,Body 和 Footer 可以省略。
<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>
Header
Header 部分只有一行,包括三个字段:type
(必需)、scope
(可选)和subject
(必需)。
不管是哪一个部分,任何一行都不得超过72个字符(或100个字符)。这是为了避免自动换行影响美观。
type
type
用于说明提交的类别
- 主要type
- feat:新功能(feature)
- fix:修补bug
- 特殊type
- docs:只改动了文档相关的内容(documentation)
- style:代码格式(不影响代码运行的变动)
- build:构造工具的或者外部依赖的改动,例如webpack,npm
- refactor: 代码重构时使用
- revert: 执行git revert打印的message
- 较少使用type
- perf:性能优化(Performance improvement)
- test:测试方便的改动
- ci:与持续集成服务有关的改动
- chore:不修改src或者test的其余修改,例如构建过程或辅助工具的变动
scope
scope
用于说明提交影响的范围,比如数据层、控制层、视图层等等,视项目不同而不同。
subject
subject
是提交目的的简短描述,不超过50个字符。
Body
Body 部分是对本次 Commit 的详细描述,可以分成多行。
Footer
Footer 部分只用于两种情况。
-
不兼容变动
如果当前代码与上一个版本不兼容,则 Footer 部分以
BREAKING CHANGE
开头,后面是对变动的描述、以及变动理由和迁移方法。 -
关闭 Issue
如果当前 Commit 针对某个 issue,那么可以在 Footer 部分关闭这个 issue 。
Closes #234
也可以一次关闭多个 issue 。
Closes #123, #245, #992
Revert
Revert 是一种特殊情况,用于撤销以前的 Commit。其必须以revert:
开头,后面跟着被撤销 Commit 的 Header。
revert: feat(pencil): add 'graphiteWidth' option
This reverts commit 667ecc1654a317a13331b17617d973392f415f02.
Body 部分的格式是固定的,必须写成 This reverts commit commit_id
Change log
Change Log 是发布新版本时,用来说明与上一个版本差异的文档,一般包含 "Feature","Fix","Performance Improvement"与"Breaking Changes"。
如果你的所有 Commit 都符合 Angular 格式,那么发布新版本时,Change log 就可以用脚本自动生成,方法如下:
全局安装 conventional-changelog-cli
npm install -g conventional-changelog-cli@2.2.2
在你的项目根目录中执行
conventional-changelog -p angular -i CHANGELOG.md -s
这不会覆盖任何以前的变更日志。只会在 CHANGELOG.md
的头部加上自从上次发布以来的变动。
如果你是第一次使用并且你想生成所有以前的更改日志,可以执行
conventional-changelog -p angular -i CHANGELOG.md -s -r 0
这将覆盖任何以前的更改日志。
/*
* 配置项说明:
* -p angular 指定风格
* -i CHANGELOG.md 指定输出的文件名称
* -s 指定增量更新,不会覆盖以前的更新日志
* -r 0 从最新的版本生成多少个版本的日志,如果为0,则日志将重新生成。
*/
你可以在项目配置文件 package.json
中添加脚本以简便操作。
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
生成日志如下图:
配置 Commit 规范
格式化规范工具 Commitizen
可以利用 Commitizen,帮助我们撰写规范的提交信息,方法如下:
安装 commitizen 和 cz-customizable
npm install -g commitizen@4.2.4
npm install -D cz-customizable@6.3.0
在 package.json
中进行新增
"config": {
"commitizen": {
"path": "node_modules/cz-customizable"
}
}
在根目录下新建 .cz-config.js
文件并写入配置
module.exports = {
// 可选类型
types: [
{ value: 'feat', name: 'feat: 新功能' },
{ value: 'fix', name: 'fix: 修复' },
{ value: 'docs', name: 'docs: 文档变更' },
{ value: 'style', name: 'style: 代码格式(不影响代码运行的变动)' },
{ value: 'refactor', name: 'refactor: 重构' },
{ value: 'perf', name: 'perf: 性能优化' },
{ value: 'test', name: 'test: 增加测试' },
{ value: 'chore', name: 'chore: 构建过程或辅助工具的变动' },
{ value: 'revert', name: 'revert: 回退' },
{ value: 'build', name: 'build: 打包' },
{ value: 'ci', name: 'ci: 与持续集成服务有关的改动' },
],
// 消息步骤
messages: {
type: '请选择提交类型:',
customScope: '请输入修改范围(可选):',
subject: '请简要描述提交(必填):',
body: '请输入详细描述(可选):',
footer: '请输入要关闭的issue(可选):',
confirmCommit: '确认使用以上信息提交?(y/n/e/h)',
},
// 跳过问题
skipQuestions: ['footer'],
// subject文字长度默认是72
subjectLimit: 72,
}
之后就可以用 git cz
来代替 git commit
。
git cz
cz-cli@4.2.4, cz-customizable@6.3.0
All lines except first will be wrapped after 100 characters.
? 请选择提交类型: (Use arrow keys)
> feat: 新功能
fix: 修复
docs: 文档变更
style: 代码格式(不影响代码运行的变动)
refactor: 重构
perf: 性能优化
test: 增加测试
? 请输入修改范围(可选):
? 请简要描述提交(必填): 新功能xxx
? 请输入详细描述(可选):
? 请输入要关闭的issue(可选):
###--------------------------------------------------------###
feat: 新功能xxx
###--------------------------------------------------------###
? 确认使用以上信息提交?(y/n/e/h)
- cz-customizable 是一款shell插件,无法在
git bash
中正常使用
使用 Husky 强制执行规范
只是我们自己遵守规范是不够的,要让项目的所有开发者,都强制遵守此规范,可以通过 Commitlint 与 Husky 来实现,方法如下:
安装 commitlint/cli 与 commitlint/config-conventional
npm install -D @commitlint/config-conventional@12.1.4 @commitlint/cli@12.1.4
添加 commitlint 的配置文件 commitlint.config.js
并写入配置
module.exports = {
// 继承的规则
extends: ['@commitlint/config-conventional'],
// 定义规则类型
rules: {
// type 类型定义,表示 git 提交的 type 必须在以下类型范围内
'type-enum': [
2,
'always',
[
'feat', // 新功能 feature
'fix', // 修复 bug
'docs', // 文档注释
'style', // 代码格式(不影响代码运行的变动)
'refactor', // 重构(既不增加新功能,也不是修复bug)
'perf', // 性能优化
'test', // 增加测试
'chore', // 构建过程或辅助工具的变动
'revert', // 回退
'build', // 打包
'ci', // 与持续集成服务有关的改动
],
],
// subject 大小写不做校验
'subject-case': [0],
},
}
安装 husky
npm install -D husky@7.0.1
初始化 husky
npx husky install
将 husky 与commitlint 进行关联,执行
npx husky add .husky/commit-msg
在生成的 commit-msg
文件中写入指令 (替换undefined)
npx --no-install commitlint --edit
这样子就配置完成了,进行不符合规范的提交时,命令行就会报错
git commit -m 'hello world'
⧗ input: hello world
✖ subject may not be empty [subject-empty]
✖ type may not be empty [type-empty]
✖ found 2 problems, 0 warnings
ⓘ Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint
husky - commit-msg hook exited with code 1 (error)
只有攥写符合规范的提交说明,才能成功提交
git commit -m 'feat: 新功能xxx'
[master 84d6807] feat: 新功能xxx
3 files changed, 12 insertions(+), 6 deletions(-)
delete mode 100644 .husky/pre-commit
内容参考自:
Commit message 和 Change log 编写指南
commIt type - CSDN
commit 规范配置教程