Yaitza

Git 提交规范

1. 具体规则

先来看看公式:

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

1.1 type:用于说明 commit 的类别,只允许使用下面7个标识。

  • FEAT:新功能【feature】
  • FIX:修补bug
  • DOC:文档【documentation】
  • STYLE: 格式【不影响代码运行的变动】
  • REFACTOR:重构【即不是新增功能,也不是修改bug的代码变动】
  • TEST:增加测试
  • CHORE:构建过程或辅助工具的变动

1.2 id:对应新功能或者bug对应的id编号。

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

subject:是 commit 目的的简短描述,不超过50个字符。

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

1.4 body:部分是对本次 commit 的详细描述,可以分成多行。

1
2
3
4
5
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

有两个注意点:
(1)使用第一人称现在时,比如使用change而不是changed或changes。
(2)应该说明代码变动的动机,以及与以前行为的对比。

1.5.1 不兼容变动

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

1
2
3
4
5
6
7
8
9
10
11
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.

1.5.2 关闭 Issue

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

1
Closes #234

也可以一次关闭多个 issue 。

1
Closes #123, #245, #992

1.6 Revert:还有一种特殊情况,如果当前 commit 用于撤销以前的 commit,则必须以revert:开头,后面跟着被撤销 Commit 的 Header。

1
2
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. 异常处理

我们先来看看这个异常提醒:

1
2
INVALID COMMIT MSG: does not match "<type>(<scope>): <subject>" !
jartto:fix bug

这里之所以报出这个警告,是因为我的提交出现了两个问题:
其一,使用了规范外的关键字;
其二,很细节的问题,jartto:后少了空格。
这时候我才回忆起来,当时提交一直失败,情急之下直接强制提交,所以以后的提交都会抱出这个异常。大致意思就是:
你的之前的 Commit 不合格~你的之前的 Commit 不合格~你的之前的 Commit 不合格
这时候就很烦了,我们只能去将之前的错误修正,那么如何操作呢?

3. 如何修改之前的 Commit 信息?

其实并不复杂,我们只需要这样做:

  1. 将当前分支无关的工作状态进行暂存
    1
    git stash
  2. 将 HEAD 移动到需要修改的 commit 上
    1
    git rebase 9633cf0919^ --interactive
  3. 找到需要修改的 Commit,将首行的 pick 改成 edit
  4. 开始着手解决你的 bug
  5. git add 将改动文件添加到暂存
  6. git commit –amend 追加改动到提交
  7. git rebase –continue 移动 HEAD 回最新的 commit
  8. 恢复之前的工作状态
    1
    git stash pop

4. 项目中使用

这时候问题又来了,为什么我提交的时候会有警告,这个又是如何做到的呢?
这时候,我们需要一款 Node 插件 validate-commit-msg 来检查项目中 Commit message 是否规范。

4.1 首先,安装插件:

1
npm install --save-dev validate-commit-msg

4.2 使用方式一,建立 .vcmrc 文件:

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
}

4.3 使用方式二:写入 package.json

1
2
3
4
5
6
7
{
"config": {
"validate-commit-msg": {
/* your config here */
}
}
}

4.4 可是我们如果想自动使用 ghooks[3] 钩子函数呢?

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{

"config": {
"ghooks": {
"pre-commit": "gulp lint",
"commit-msg": "validate-commit-msg",
"pre-push": "make test",
"post-merge": "npm install",
"post-rewrite": "npm install",

}
}

}

在 ghooks 中我们可以做很多事情,当然不只是 validate-commit-msg 哦。更多细节请参考:validate-commit-msg[4]。

5. Commit 规范的作用

  1. 提供更多的信息,方便排查与回退;
  2. 过滤关键字,迅速定位;
  3. 方便生成文档。

6. 生成 Change log

正如上文提到的生成文档,如果我们的提交都按照规范的话,那就很简单了。生成的文档包括以下三个部分:

  • New features
  • Bug fixes
  • Breaking changes

每个部分都会罗列相关的 commit ,并且有指向这些 commit 的链接。当然,生成的文档允许手动修改,所以发布前,你还可以添加其他内容。
这里需要使用工具 Conventional Changelog[5] 生成 Change log :

1
2
3
npm install -g conventional-changelog
cd jartto-domo
conventional-changelog -p angular -i CHANGELOG.md -w

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

  1. 过滤关键字,迅速定位;
  2. 方便生成文档。

7. 生成 Change log

正如上文提到的生成文档,如果我们的提交都按照规范的话,那就很简单了。生成的文档包括以下三个部分:

  • New features
  • Bug fixes
  • Breaking changes

每个部分都会罗列相关的 commit ,并且有指向这些 commit 的链接。当然,生成的文档允许手动修改,所以发布前,你还可以添加其他内容。
这里需要使用工具 Conventional Changelog[5] 生成 Change log :

1
2
3
4
5
{
"scripts": {
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -w -r 0"
}
}

这样,使用起来就很简单了:

npm run changelog

参考文献:

  1. http://www.ruanyifeng.com/blog/2016/01/commit_message_change_log.html
  2. https://www.aliyun.com/jiaocheng/125261.html
  3. https://www.npmjs.com/package/ghooks
  4. https://github.com/conventional-changelog-archived-repos/validate-commit-msg
  5. https://github.com/conventional-changelog/conventional-changelog
🐶 您的支持将鼓励我继续创作 🐶