使用 commitizen 规范git提交说明

我们保存本地代码是用命令

git add . 
git commit -m 'xxx'
1
2

commitize的作用就是代替git commit ,用来规范git提交说明；

1. 规范的提交格式

符合规范的Commit Message的提交格式如下，包含了页眉（header）、正文（body）和页脚（footer）三部分。其中，header是必须的，body和footer可以忽略。

Header

Header 部分只有一行，包括三个字段：提交类型type（必需）、作用域scope（可选）、主题subject（必需）

作用域（scope）表示此次提交影响的范围。比如可以取值api，表明只影响了接口。

主题（subject）描述是简短的一句话，简单说明此次提交的内容

正文（body）和页眉（footer）

正文（body）和页眉（footer）这两部分不是必须的。

如果是破坏性的变更，那就必须在提交的正文或脚注加以展示。一个破坏性变更必须包含大写的文本 BREAKING CHANGE，紧跟冒号和空格。脚注必须只包含 BREAKING CHANGE、外部链接、issue 引用和其它元数据信息。例如修改了提交的流程，依赖了一些包，可以在正文写上：BREANKING CHANGE：需要重新npm install，使用npm run cm代替git commit。

下面给出了一个Commit Message例子，该例子中包含了header和body。
chore: 引入commitizen

BREANKING CHANGE：需要重新npm install，使用npm run cm代替git commit

当然，在平时的提交中，我们也可以只包含header，比如我们修改了登录页面的某个功能，那么可以这样写Commit Message。

feat(登录）：添加登录接口

2. Commitizen

虽然有了规范，但是还是无法保证每个人都能够遵守相应的规范，因此就需要使用一些工具来保证大家都能够提交符合规范的Commit Message。常用的工具包括了可视化工具和信息交互工具，其中Commitizen是常用的Commitizen工具，接下来将会先介绍Commitizen的使用方法。
commitizen

安装

npm install commitizen -g
1

npm install commitizen cz-conventional-changelog --save-dev
1

配置

package.json

"config": {
  "commitizen": {
    "path": "./node_modules/cz-conventional-changelog"
  }
}
1
2
3
4
5

使用

git cz
1

3. 生成 Change log 文件

conventional-changelog 就是生成 Change log 的工具，运行下面的命令即可。

npm install -g conventional-changelog
1

如果你想生成所有发布的 Change log，要改为运行下面的命令。

conventional-changelog -p angular -i CHANGELOG.md -w -r 0
1

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

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

以后，直接运行下面的命令即可。

npm run changelog
1

但是我执行命令时候 报错 告诉我 sh: conventional-changelog: command not found；
很奇怪 明明已经安装过，最后在这篇文章 Git 提交记录和分支模型中发现

conventional-changelog-cli：通过提交记录生成 CHANGELOG.md
conventional-github-releaser：通过提交记录生成 github release 中的变更描述
conventional-recommended-bump：根据提交记录判断需要升级 Semantic Versioning 哪一位版本号
validate-commit-msg：检查提交记录是否符合约定

所以就改用了conventional-changelog-cli：

npm install conventional-changelog-cli --save
1

这时候执行npm run changelog 发现可以执行，并且在命令行中出 CHANGELOG 的内容，但我想要的是生成CHANGELOG文件，需要使用

// 基于上次 tag 版本之后的变更（Feature、Fix、Breaking Changes等等）所产生的
conventional-changelog -p angular -i CHANGELOG.md -s

// 项目正式使用。--- 生成之前所有 commit 信息产生的 changelog 
conventional-changelog -p angular -i CHANGELOG.md -s -r 0
1
2
3
4
5

更多的 config 可以使用 conventional-changelog --help 查看
以上命令中参数-p angular用来指定使用的 commit message 标准； angular 就是指定的使用的 commit message 标准；
参数-i CHANGELOG.md表示从 CHANGELOG.md 读取 changelog,
-s 表示读写 changelog 为同一文件。
其中 -r 表示生成 changelog 所需要使用的 release 版本数量，默认为1，全部则是0。

⚠️还需要注意的是，在生成 changlog 之前，需要先使用 $ npm version [version] 更改版本号，然后再生成 changelog，这一步很多的博文都没有写，就会导致增量生成的 CHANGELOG 一直都有之前的 commit 记录。

4. standard-version

现在就可以使用 standard-version 进行版本管理自动化，包括更新 CHANGELOG.md，它也会自动修改 package.json 里的 version。
standard-version 是一款遵循语义化版本（ semver）和 commit message 标准规范 的版本和 changlog 自动化工具。
一般来说 我们的发版流程如下

• 切到master git pull origin master
• 根据 pacakage.json 中的 version 更新版本号，更新 changelog
• git add ., 然后 git commit
• git tag 打版本操作
• push 版本 tag 和 master 分支到仓库

其中2，3，4则是 standard-version 工具会自动完成的工作，配合本地的 shell 脚本，则可以自动完成一系列版本发布的工作了。

安装

npm install --save-dev standard-version
1

在 package.json 中编写：

"scripts": {
  "release": "standard-version"，
}
1
2
3

–release-as或者-r 指定版本号
主版本（major）,次版本（ minor） or 修订版（patch）

"scripts": {
    "release": "standard-version",
    "release:major": "standard-version -- --release-as major",
    "release:minor": "standard-version -- --release-as minor"
  },

1
2
3
4
5
6

为了合理的使用 standard-version，我们首先需要 git add . 文件，然后执行 npm run commit 提交，最后执行 npm run release。

执行完以后就会在项目根目录自动生成 CHANGELOG.md 文件。

默认情况下，standard-version 只会在 CHANGELOG.md 中记录 feat 和 fix 类型的提交。如果想记录其他类型的提交，需要如下步骤：

在项目的根目录下创建一个名为 .versionrc 的文件，并粘贴复制一下内容：

{
  "types": [
    {"type": "chore", "section":"Others", "hidden": false},
    {"type": "revert", "section":"Reverts", "hidden": false},
    {"type": "feat", "section": "Features", "hidden": false},
    {"type": "fix", "section": "Bug Fixes", "hidden": false},
    {"type": "improvement", "section": "Feature Improvements", "hidden": false},
    {"type": "docs", "section":"Docs", "hidden": false},
    {"type": "style", "section":"Styling", "hidden": false},
    {"type": "refactor", "section":"Code Refactoring", "hidden": false},
    {"type": "perf", "section":"Performance Improvements", "hidden": false},
    {"type": "test", "section":"Tests", "hidden": false},
    {"type": "build", "section":"Build System", "hidden": false},
    {"type": "ci", "section":"CI", "hidden":false}
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

type------commit 类型
section------不同的 commit 类型所在 CHANGELOG.md 中的区域
hidden------是否在 CHANGELOG.md 中显示

-r 指定版本号
standard-version -r 2.0.0自定义版本号2.0.0

–tag-prefix, -t 版本 tag 前缀
用来给生成 tag 标签添加前缀，例如如果前版本号为 2.0.0，则：
standard-version --tag-prefix "tags-"输出版本tags-v2.0.0

–tag-prefix, -t 版本 tag 前缀
用来给生成 tag 标签添加前缀，例如如果前版本号为 2.0.0，则：
standard-version --tag-prefix "tags-"输出版本tags-v2.0.0

5. 可视化提交工具

在VSCode的EXTENSIONS中找到git-commit-plugin插件，点击install进行安装。

安装完成之后，可以通过git add添加要提交的文件，接着，在Source Control点击show git commit template图标，开始编写Commit Message信息。

接下来只需要按照指引进行Commit Message的编写。

当编写完成之后，可以得到符合规范的Commit Message，这个时候就可以放心将Commit Message及所修改的文件进行提交啦。

其他博主优秀文
阮一峰