billfeller.github.io Git commit message 规范化工程实践

Git commit message 规范化工程实践

Open billfeller opened this issue 6 years ago • 0 comments

阮一峰于2016撰写了《Commit message 和 Change log 编写指南》，但是文中部分内容工具已变更，是故本文可以理解为其更新优化版本，文末还讨论了配置服务器端钩子实现提交强制校验的必要性。

文字内容包括 1）为什么需要规范化Commit message； 2）如何通过工具实现Commit message提交约定规范（本文默认采用符合Angular撰写规范） 3）规范化Commit message带来了哪些好处。

一、为什么需要规范化Commit message

Git 每次提交代码，都要写Commit message，否则就不允许提交。 bash # 输入单行命令 $ git commit -m "{{message}}" # 输入多行命令： $ git commit

其中，{{message}}可以填写任意内容。

但是，对于合理的团队开发流程，需要对{{message}}做写法规范限制，以便更好地说明提交内容。

二、如何通过工具实现Commit message提交约定规范

首先通过以下流程图，展示引入约定工具前后流程变化，仅仅只需将git commit变更为git cz，理解规范引入的几个浅显易懂的约定类型概念，其他对业务开发透明。

安装commitlint：

# Install commitlint cli and angular config
$ npm install --save-dev @commitlint/{config-conventional,cli}
# For Windows:
$ npm install --save-dev @commitlint/config-conventional @commitlint/cli

# Configure commitlint to use angular config
$ echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js

安装Git钩子工具husky：
```
$ npm install --save-dev husky
```

添加commitmsg钩子：

{
    "scripts": {
        "commitmsg": "commitlint -e $GIT_PARAMS"
    }
}

测试Commit message功能：

$ git commit -m "foo: this will fail"
husky > npm run -s commitmsg

⧗   input: foo: this will fail
:heavy_multiplication_x:   type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test] [type-enum]
:heavy_multiplication_x:   found 1 problems, 0 warnings

husky > commit-msg hook failed (add --no-verify to bypass)

$ git commit -m "chore: lint on commitmsg"
husky > npm run -s commitmsg

⧗   input: chore: lint on commitmsg
:heavy_check_mark:   found 0 problems, 0 warnings

全局安装Commitizen（撰写合格Commit message的工具），规范化Commit message书写规范：
```
$ npm install -g commitizen
```

在工程根目录中执行如下命令：

$ commitizen init cz-conventional-changelog --save --save-exact

使用git cz替换git commit提交变更：

$ git cz
[email protected], [email protected]
Line 1 will be cropped at 100 characters. All other lines will be wrapped after 100 characters.
? Select the type of change that you're committing: feat:     A new feature
? Denote the scope of this change ($location, $browser, $compile, etc.):
? Write a short, imperative tense description of the change:
 test
? Provide a longer description of the change:

? List any breaking changes or issues closed by this change:

husky > npm run -s commitmsg (node v8.11.1)

⧗   input: feat: test
:heavy_check_mark:   found 0 problems, 0 warnings

[uitest_with_puppeteer cf19d06] feat: test
 2 files changed, 63 insertions(+), 10 deletions(-)

三、规范化Commit message带来了哪些好处

格式化的Commit message，有以下几个好处。

提供更多的历史信息，方便快速浏览。 比如，下面的命令显示上次发布后的变动，每个commit占据一行。你只看行首，就知道某次 commit 的目的。
```
$ git log HEAD --pretty=format:%s
feat: test
```

可以过滤某些commit（比如文档改动），便于快速查找信息。 比如，下面的命令仅仅显示本次发布新增加的功能。

$ git log HEAD --grep feat
commit 009fb2d2cbbf61843d725795f11561e8480e94b1 (HEAD -> master)
Author: xxxx
Date:   Wed May 23 17:28:19 2018 +0800

    feat: test

从Commit message中生成可读的changelog。 changelog是发布新版本时，用来说明与上一个版本差异的文档。通过conventional-changelog-cli 工具可以从git元数据中导出Commit message，生成可读的CHANGELOG.md。
```
$ npm install --save-dev conventional-changelog-cli
$ conventional-changelog -p angular -i CHANGELOG.md -s -r 0
```
可以将以上命令集成到npm scripts，在package.json添加如下配置：
```
{
  "scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0 && git add CHANGELOG.md"
  }
}
```

四、配置服务器端钩子实现提交强制校验

以上示例演示了如何通过本地钩子实现Commit message规范化，但是本地提交规范通过--force直接跳过，这意味着这不是一个严格的开发流程，所以需要通过服务器端钩子，进行服务端的二次校验，才可以实现强制规范。

五、遇到的问题

windows下git-bash中执行git cz无法通过箭头选择提交类型，推荐使用cmder工具；
windows下cmder展示utf8中文编码问题，推荐国际惯例约定提交英文message；

六、更多阅读

Apr 20 '18 13:04 billfeller

billfeller.github.io billfeller.github.io copied to clipboard

Git commit message 规范化工程实践

一、为什么需要规范化Commit message

二、如何通过工具实现Commit message提交约定规范

三、规范化Commit message带来了哪些好处

四、配置服务器端钩子实现提交强制校验

五、遇到的问题

六、更多阅读

billfeller.github.io
billfeller.github.io copied to clipboard