Cz工具集使用介绍 - 规范Git提交说明

在多人协作的项目中，如果Git的提交说明精准，在后期协作以及Bug处理时会变得有据可查，项目的开发可以根据规范的提交说明快速生成开发日志，从而方便开发者或用户追踪项目的开发信息和功能特性。

本文主要内容：

介绍符合Angular规范（需要翻墙）的提交说明
介绍提交说明工具集cz（适配器、校验以及日志）的使用方法
介绍供开发者快速生成项目cz工具集的Vue CLI 3插件@ziyi2/ui-cz

这里提供演示项目地址：cz-example。

Git的提交说明

Git每次提交代码的时候都需要手写提交说明（Commit message）：

git commit -m "hello world"

书写多行可以使用以下命令：

git commit

此时会跳出一个文本编辑器，可以在文本编辑器中书写多行提交说明：

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch master
# Your branch is up to date with 'origin/master'.
#
# Changes to be committed:
#       new file:   package.json
#
G:/git-lab/cz/.git/COMMIT_EDITMSG [unix] (19:49 24/01/2019)

如果没有规范的提交说明，很难阐述当前代码的提交性质（修复Bug、代码性能优化、新增功能或者发布版本等）。查看Vue项目的Git提交说明（fix表明修复问题、feat表明新增功能...），它完全符合Angular规范：

enter image description here

手写符合规范的提交说明很难避免错误，可以借助工具来实现规范的提交说明。

规范的Git提交说明

提供更多的历史信息，方便快速浏览
可以过滤某些commit，便于筛选代码review
可以追踪commit生成更新日志
可以关联issues

`Git`提交说明结构

Git提交说明可分为三个部分：Header、Body和Footer。

<Header> <Body> <Footer>

`Header`

Header部分包括三个字段type（必需）、scope（可选）和subject（必需）。

<type>(<scope>): <subject>

Vue源码的提交说明省略了scope。

`type`

type用于说明 commit 的提交性质。

值	描述
feat	新增一个功能
fix	修复一个Bug
docs	文档变更
style	代码格式（不影响功能，例如空格、分号等格式修正）
refactor	代码重构
perf	改善性能
test	测试
build	变更项目构建或外部依赖（例如scopes: webpack、gulp、npm等）
ci	更改持续集成软件的配置文件和package中的scripts命令，例如scopes: Travis, Circle等
chore	变更构建流程或辅助工具
revert	代码回退

`scope`

scope说明commit影响的范围。scope依据项目而定，例如在业务项目中可以依据菜单或者功能模块划分，如果是组件库开发，则可以依据组件划分。

提示：scope可以省略。

`subject`

subject是commit的简短描述。

`Body`

commit的详细描述，说明代码提交的详细说明。

`Footer`

如果代码的提交是不兼容变更或关闭缺陷，则Footer必需，否则可以省略。

不兼容变更

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

关闭缺陷

如果当前提交是针对特定的issue，那么可以在Footer部分填写需要关闭的单个 issue 或一系列issues。

Commitizen

commitizen/cz-cli是一个可以实现规范的提交说明的工具：

When you commit with Commitizen, you'll be prompted to fill out any required commit fields at commit time. No more waiting until later for a git commit hook to run and reject your commit (though that can still be helpful). No more digging through CONTRIBUTING.md to find what the preferred format is. Get instant feedback on your commit message formatting and be prompted for required fields.

提供选择的提交信息类别，快速生成提交说明。安装cz工具:

npm install -g commitizen

Commitizen适配器

cz-conventional-changelog

如果需要在项目中使用commitizen生成符合AngularJS规范的提交说明，初始化cz-conventional-changelog适配器：

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

如果当前已经有其他适配器被使用，则会报以下错误，此时可以加上--force选项进行再次初始化

Error: A previous adapter is already configured. Use --force to override

初始化命令主要进行了3件事情

在项目中安装cz-conventional-changelog 适配器依赖
将适配器依赖保存到package.json的devDependencies字段信息
在package.json中新增config.commitizen字段信息，主要用于配置cz工具的适配器路径：

"devDependencies": {
 "cz-conventional-changelog": "^2.1.0"
},
"config": {
  "commitizen": {
    "path": "./node_modules/cz-conventional-changelog"
  }
}

接下来可以使用cz的命令git cz代替git commit进行提交说明：

enter image description here

代码提交到远程的Github后，可以在相应的项目中进行查看，例如（这里使用feat不是很合适，只是一个示例）：

enter image description here

cz-customizable

如果想定制项目的提交说明，可以使用cz-customizable适配器：

Suitable for large teams working with multiple projects with their own commit scopes. When you specify the scopes in your .cz-config.js, cz-customizable allows you to select the pre-defined scopes. No more spelling mistakes embarrassing you when generating the changelog file.

安装适配器

npm install cz-customizable --save-dev

将之前符合Angular规范的cz-conventional-changelog适配器路径改成cz-customizable适配器路径：

"devDependencies": {
  "cz-customizable": "^5.3.0"
},
"config": {
  "commitizen": {
    "path": "node_modules/cz-customizable"
  }
}

cz-customizable will first look for a file called .cz-config.js，alternatively add a config block in your package.json。

官方提供了一个.cz-config.js示例文件cz-config-EXAMPLE.js，如下所示：

'use strict';

module.exports = {

  types: [
    {value: 'feat',     name: 'feat:     A new feature'},
    {value: 'fix',      name: 'fix:      A bug fix'},
    {value: 'docs',     name: 'docs:     Documentation only changes'},
    {value: 'style',    name: 'style:    Changes that do not affect the meaning of the code\n            (white-space, formatting, missing semi-colons, etc)'},
    {value: 'refactor', name: 'refactor: A code change that neither fixes a bug nor adds a feature'},
    {value: 'perf',     name: 'perf:     A code change that improves performance'},
    {value: 'test',     name: 'test:     Adding missing tests'},
    {value: 'chore',    name: 'chore:    Changes to the build process or auxiliary tools\n            and libraries such as documentation generation'},
    {value: 'revert',   name: 'revert:   Revert to a commit'},
    {value: 'WIP',      name: 'WIP:      Work in progress'}
  ],

  scopes: [
    {name: 'accounts'},
    {name: 'admin'},
    {name: 'exampleScope'},
    {name: 'changeMe'}
  ],

  // it needs to match the value for field type. Eg.: 'fix'
  /*
  scopeOverrides: {
    fix: [
      {name: 'merge'},
      {name: 'style'},
      {name: 'e2eTest'},
      {name: 'unitTest'}
    ]
  },
  */
  // override the messages, defaults are as follows
  messages: {
    type: 'Select the type of change that you\'re committing:',
    scope: '\nDenote the SCOPE of this change (optional):',
    // used if allowCustomScopes is true
    customScope: 'Denote the SCOPE of this change:',
    subject: 'Write a SHORT, IMPERATIVE tense description of the change:\n',
    body: 'Provide a LONGER description of the change (optional). Use "|" to break new line:\n',
    breaking: 'List any BREAKING CHANGES (optional):\n',
    footer: 'List any ISSUES CLOSED by this change (optional). E.g.: #31, #34:\n',
    confirmCommit: 'Are you sure you want to proceed with the commit above?'
  },

  allowCustomScopes: true,
  allowBreakingChanges: ['feat', 'fix'],

  // limit subject length
  subjectLimit: 100
  
};

这里对其进行汉化处理（只是为了说明定制说明的一个示例）：

'use strict';

module.exports = {

  types: [
    {value: '特性',     name: '特性:    一个新的特性'},
    {value: '修复',      name: '修复:    修复一个Bug'},
    {value: '文档',     name: '文档:    变更的只有文档'},
    {value: '格式',    name: '格式:    空格, 分号等格式修复'},
    {value: '重构', name: '重构:    代码重构，注意和特性、修复区分开'},
    {value: '性能',     name: '性能:    提升性能'},
    {value: '测试',     name: '测试:    添加一个测试'},
    {value: '工具',    name: '工具:    开发工具变动(构建、脚手架工具等)'},
    {value: '回滚',   name: '回滚:    代码回退'}
  ],

  scopes: [
    {name: '模块1'},
    {name: '模块2'},
    {name: '模块3'},
    {name: '模块4'}
  ],

  // it needs to match the value for field type. Eg.: 'fix'
  /*
  scopeOverrides: {
    fix: [
      {name: 'merge'},
      {name: 'style'},
      {name: 'e2eTest'},
      {name: 'unitTest'}
    ]
  },
  */
  // override the messages, defaults are as follows
  messages: {
    type: '选择一种你的提交类型:',
    scope: '选择一个scope (可选):',
    // used if allowCustomScopes is true
    customScope: 'Denote the SCOPE of this change:',
    subject: '短说明:\n',
    body: '长说明，使用"|"换行(可选)：\n',
    breaking: '非兼容性说明 (可选):\n',
    footer: '关联关闭的issue，例如：#31, #34(可选):\n',
    confirmCommit: '确定提交说明?'
  },

  allowCustomScopes: true,
  allowBreakingChanges: ['特性', '修复'],

  // limit subject length
  subjectLimit: 100

};

再次使用git cz命令进行提交说明：

enter image description here

从上图可以看出此时的提交说明选项已经汉化，继续填写提交说明：

enter image description here

把代码提交到远程看看效果：

enter image description here

Commitizen校验

commitlint

校验提交说明是否符合规范，安装校验工具commitlint：

npm install --save-dev @commitlint/cli

@commitlint/config-conventional

安装符合Angular风格的校验规则

npm install --save-dev @commitlint/config-conventional

在项目中新建commitlint.config.js文件并设置校验规则：

module.exports = {
  extends: ['@commitlint/config-conventional']
};

安装huksy（git钩子工具）

npm install husky --save-dev

在package.json中配置git commit提交时的校验钩子：

"husky": {
  "hooks": {
    "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
  }  
}

需要注意，使用该校验规则不能对.cz-config.js进行不符合Angular规范的定制处理，例如之前的汉化，此时需要将.cz-config.js的文件按照官方示例文件cz-config-EXAMPLE.js进行符合Angular风格的改动。

执行错误的提交说明：

enter image description here

执行符合Angular规范的提交说明：

enter image description here

commitlint需要配置一份校验规则，@commitlint/config-conventional就是符合Angular规范的一份校验规则。

commitlint-config-cz

如果是使用cz-customizable适配器做了破坏Angular风格的提交说明配置，那么不能使用**@commitlint/config-conventional**规则进行提交说明校验，可以使用commitlint-config-cz对定制化提交说明进行校验。

安装校验规则：

npm install commitlint-config-cz --save-dev

然后加入commitlint校验规则配置：

module.exports = {
  extends: [
    'cz'
  ]
};

这里推荐使用**@commitlint/config-conventional**校验规则，如果想使用cz-customizable适配器，那么定制化的配置不要破坏Angular规范即可。

validate-commit-msg

除了使用commitlint校验工具，也可以使用validate-commit-msg校验工具对cz提交说明是否符合Angular规范进行校验。

Commitizen日志

如果使用了cz工具集，配套conventional-changelog可以快速生成开发日志：

npm install conventional-changelog -D

在pacage.json中加入生成日志命令：

"version": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0 && git add CHANGELOG.md"

You could follow the following workflow

Make changes
Commit those changes
Pull all the tags
Run the npm version [patch|minor|major] command
Push

执行npm run version后可查看生产的日志CHANGELOG.md。

注意要使用正确的Header的type，否则生成的日志会不准确，这里只是一个示例，生成的日志不是很严格。

Vue CLI 3 插件

如果对于上述所说的配置感到繁琐，这里提供一个Vue CLI 3的插件，如果开发的项目由Vue CLI 3系统生成，可以使用插件@ziyi2/ui-cz一键生成：

vue add @ziyi2/ui-cz

该插件采用了cz-customizable定制化提交说明的适配器、@commitlint/config-conventional校验规则以及conventional-changelog日志生成器。

总结

呼吁大家书写规范的提交说明，代码说明不规范，项目成员泪两行。演示项目地址：cz-example。

链接

Angular规范
cz-cli - cz工具
cz-customizable - cz适配器
@commitlint/config-conventional - cz适配器
commitlint - cz校验工具
commitlint-config-cz - cz校验工具的校验规则
validate-commit-msg - cz校验工具
conventional-changelog - cz日志生成器
commit_msg - git钩子文档

Cz工具集使用介绍 - 规范Git提交说明

广告

Git的提交说明

规范的Git提交说明

Git提交说明结构

Header

type

scope

subject

Body

Footer

不兼容变更

关闭缺陷

Commitizen

Commitizen适配器

cz-conventional-changelog

cz-customizable

Commitizen校验

commitlint

@commitlint/config-conventional

commitlint-config-cz

validate-commit-msg

Commitizen日志

Vue CLI 3 插件

总结

链接

`Git`提交说明结构

`Header`

`type`

`scope`

`subject`

`Body`

`Footer`