一、为什么要规范化Commit message
格式化的Commit message，有几个好处。
（1）提供更多的历史信息，方便快速浏览。
比如，下面的命令显示上次发布后的变动，每个commit占据一行。你只看行首，就知道某次 commit 的目的。
$ git log <last tag> HEAD --pretty=format:%s
（2）可以过滤某些commit（比如文档改动），便于快速查找信息。
比如，下面的命令仅仅显示本次发布新增加的功能。
$ git log <last release> HEAD --grep feature
（3）可以直接从commit生成Change log。
Change Log 是发布新版本时，用来说明与上一个版本差异的文档，详见后文。
二、Commit message 的格式
每次提交，Commit message 都包括三个部分：Header，Body 和 Footer。
<type>(<scope>): <subject> // 空一行 <body> // 空一行 <footer>
其中，Header 是必需的，Body 和 Footer 可以省略。
不管是哪一个部分，任何一行都不得超过72个字符（或100个字符）。这是为了避免自动换行影响美观。
2.1 Header
Header部分只有一行，包括三个字段：type（必需）、scope（可选）和subject（必需）。
（1）type
type用于说明 commit 的类别，只允许使用下面7个标识。
- feat：新功能（feature）
- fix：修补bug
- docs：文档（documentation）
- style： 格式（不影响代码运行的变动）
- refactor：重构（即不是新增功能，也不是修改bug的代码变动）
- test：增加测试
- chore：构建过程或辅助工具的变动
如果type为feat和fix，则该 commit 将肯定出现在 Change log 之中。其他情况（docs、chore、style、refactor、test）由你决定，要不要放入 Change log，建议是不要。
（2）scope
scope用于说明 commit 影响的范围，比如数据层、控制层、视图层等等，视项目不同而不同。
（3）subject
subject是 commit 目的的简短描述，不超过50个字符。
- 以动词开头，使用第一人称现在时，比如
change，而不是changed或changes- 第一个字母小写
- 结尾不加句号（
.）
2.2 Body
Body 部分是对本次 commit 的详细描述，可以分成多行。下面是一个范例。
More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. Further paragraphs come after blank lines. - Bullet points are okay, too - Use a hanging indent
注意点:
-
使用第一人称现在时，比如使用
change而不是changed或changes。 -
应该说明代码变动的动机，以及与以前行为的对比。
-
如果要编写多行 请使用
\n换行 回车直接结束描述(注意为反斜杠)
2.3 Footer
Footer 部分只用于两种情况。
（1）不兼容变动
如果当前代码与上一个版本不兼容，则 Footer 部分以BREAKING CHANGE开头，后面是对变动的描述、以及变动理由和迁移方法。
BREAKING CHANGE: isolate scope bindings definition has changed. To migrate the code follow the example below: Before: scope: { myAttr: 'attribute', } After: scope: { myAttr: '@', } The removed `inject` wasn't generaly useful for directives so there should be no code using it.
（2）关闭 Issue
如果当前 commit 针对某个issue，那么可以在 Footer 部分关闭这个 issue 。
Closes #234
也可以一次关闭多个 issue 。
Closes #123, #245, #992
2.4 Revert
还有一种特殊情况，如果当前 commit 用于撤销以前的 commit，则必须以revert:开头，后面跟着被撤销 Commit 的 Header。
revert: feat(pencil): add 'graphiteWidth' option This reverts commit 667ecc1654a317a13331b17617d973392f415f02.
Body部分的格式是固定的，必须写成This reverts commit <hash>.，其中的hash是被撤销 commit 的 SHA 标识符。
如果当前 commit 与被撤销的 commit，在同一个发布（release）里面，那么它们都不会出现在 Change log 里面。如果两者在不同的发布，那么当前 commit，会出现在 Change log 的Reverts小标题下面。
2.5 git commit 规范格式 思维导图
三、如何在项目中规范化Commit message
3.1 使用git commit模板
如果你只是个人的项目, 或者想尝试一下这样的规范格式, 那么你可以为 git 设置 commit template, 每次 git commit 的时候在 vim 中带出, 时刻提醒自己:
修改 ~/.gitconfig, 添加:
[commit]
template = ~/.gitmessage
新建~/.gitmessage 内容可以如下:
# head: <type>(<scope>): <subject>
# - type: feat, fix, docs, style, refactor, test, chore
# - 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
#
3.2 使用npm工具
Commitizen: 替代你的 git commit
我们的目标还是要通过工具生成和约束, 那么现在就开始吧.
commitizen/cz-cli, 我们需要借助它提供的git cz 命令替代我们的git commit命令, 帮助我们生成符合规范的 commit message.
除此之外, 我们还需要为 commitizen 指定一个 Adapter 比如: cz-conventional-changelog (一个符合 Angular团队规范的 preset). 使得 commitizen 按照我们指定的规范帮助我们生成 commit message.
全局安装
npm install -g commitizen cz-conventional-changelog
echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc
注意:全局模式下, 需要 ~/.czrc 配置文件, 为 commitizen 指定 Adapter.
全局安装后报错
报错信息如下
PS C:\Users\sky\WebstormProjects\Demo\React\umi> echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc
PS C:\Users\sky\WebstormProjects\Demo\React\umi> git cz
The config file at "C:\Users\sky\.czrc" contains invalid charset, expect utf8
解决方案
删除根目录下的.czrc,在vscode中新建.czrc文件,文件内容为{ "path": "cz-conventional-changelog" }
参考资料: github-commitizen-issue [Question] SyntaxError: Parsing JSON at
for commitizen config failed
项目级安装
npm install -D commitizen cz-conventional-changelog
package.json中配置:
"script": {
...,
"commit": "git-cz",
},
"config": {
"commitizen": {
"path": "node_modules/cz-conventional-changelog"
}
}
如果全局安装过commitizen, 那么在对应的项目中执行git cz or npm run commit都可以.
效果如下:
自定义 Adapter
也许 Angular 的那套规范我们不习惯, 那么可以通过指定 Adapter cz-customizable 指定一套符合自己团队的规范.
全局 或 项目级别安装:
npm i -g cz-customizable
or
npm i -D cz-customizable
修改 .czrc 或 package.json 中的 config 为:
{
"path": "cz-customizable" }
or
"config": {
"commitizen": {
"path": "node_modules/cz-customizable"
}
}
同时在~/ 或项目目录下创建 .cz-config.js 文件, 维护你想要的格式: 比如我的配置文件: leohxj/.cz-config
效果如下: