Git Commit 规范（Conventional Commit）

清香的orange
6,231 阅读5分钟

我们平时在多人协同开发的时候，经常会需要在版本发布之前手动去维护 CHANGELOG 文件。但如果开发过程没有规范 commit 提交的话，在维护 CHANGELOG 的时候也是很容易遗漏一些特性的，而且手动维护 CHANGELOG 文件也是比较繁琐的。因此就需要引入 commit message 规范来提升代码的维护效率及如何自动生成 CHANGELOG 文件。

本篇文章介绍的是 Angular 规范，这是目前使用最广的写法，比较合理和系统化，并且有配套的工具。如果需要定制 CHANGELOG 内容风格，可以参考另一篇文章 # Git Commit 规范及 CHANGELOG 定制生成 。

Commit Message 规范格式

<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>

Header

type（必填）

# 主要 type
feat:     增加新功能
fix:      修复 bug

# 特殊type
docs:     只改动了文档相关的内容
style:    不影响代码含义的改动，例如去掉空格、改变缩进、增删分号
build:    构造工具的或者外部依赖的改动，例如 webpack，npm
refactor: 代码重构时使用
revert:   执行 git revert 打印的 message

# 暂不使用type
test:     添加测试或者修改现有测试
perf:     提高性能的改动
ci:       与 CI（持续集成服务）有关的改动
chore:    不修改 src 或者 test 的其余修改，例如构建过程或辅助工具的变动

scope（非必填）

scope 用于说明 commit 影响的范围，比如数据层、控制层、视图层等等，视实际使用情况而定

subject（必填）

subject 用于说明 commit 目的的简短描述，不超过50个字符

Body

body 用于说明 commit 的详细描述，内容可以分成多行，主要描述改动之前的情况及修改动机，对于小的修改不作要求，但是重大需求、更新等尽量添加 body 来作说明

Footer

break changes

break changes 用于说明是否产生了破坏性修改(不兼容变动)，涉及 break changes 的改动必须指明该项，类似版本升级、接口参数减少、接口删除、迁移等。

affect issues

affect issues 用于说明是否影响了某个 issue。

注： 下面的 commitizen + cz-conventional-changelog 可以在提交的时候使用 git cz 命令会自动显示对应的 commit 规范信息提示

Commitizen（规范 commit 命令行工具）

安装

npm install -g commitizen

cz-conventional-changelog

使用方式（二者选其一即可）

  • 全局安装使用
npm install -g cz-conventional-changelog

全局模式下，需要 ~/.czrc 配置文件, 为 commitizen 指定 Adapter。

echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc
  • 项目中使用 运行下面的命令，使其支持 Angular 的 Commit Message 格式
commitizen init cz-conventional-changelog --save --save-exact

注意⚠️：已经通过全局方式配置的话！输入上面命令会报错（如下图）

image.png

解决：如果还是想要在项目中配置，可以按提示添加 --force 强制覆盖全局配置

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

输入上面命令后在项目根目录 package.json 文件内 会自动生成 配置信息并安装 cz-conventional-changelog

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

commit 提交

commit的时候使用 git cz 就可以根据生成自动化的提示 commit message 进行选择操作了

git cz进入 interactive 模式，根据提示依次填写

1. Select the type of change that you're committing 选择改动类型 (<type>)

2. What is the scope of this change (e.g. component or file name)? 填写改动范围 (<scope>)

3. Write a short, imperative tense description of the change: 写一个精简的描述 (<subject>)

4. Provide a longer description of the change: (press enter to skip) 对于改动写一段长描述 (<body>)

5. Are there any breaking changes? (y/n) 是破坏性修改吗？默认 n (<footer>)

6. Does this change affect any openreve issues? (y/n) 改动修复了哪个问题？默认 n (<footer>)

Commitlint & Husky（规范 commit message 验证）

  • commitlint: 用于检查提交信息;
  • husky 是 hook 工具，作用于 git-commit 和 git-push 阶段

依赖安装

npm i husky @commitlint/config-conventional @commitlint/cli -D

配置信息

commitlint 配置

根目录下新建 commitlint.config.js 配置文件，也可以在 package.json 文件内配置(二者选其一)

commitlint.config.js 文件

rules 也可以不添加使用默认的 rules 配置

更多 rules 配置信息

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'body-leading-blank': [2, 'always'], // body 开始于空白行
    'header-max-length': [2, 'always', 72], // header 字符最大长度为 72
    'subject-full-stop': [0, 'never'], // subject 结尾不加 '.'
    'type-empty': [2, 'never'], // type 不为空
    'type-enum': [2, 'always', [
      'feat', // 新特性、需求
      'fix', // bug 修复
      'docs', // 文档内容改动
      'style', // 不影响代码含义的改动，例如去掉空格、改变缩进、增删分号
      'refactor', // 代码重构
      'test', // 添加或修改测试
      'chore', // 不修改 src 或者 test 的其余修改，例如构建过程或辅助工具的变动
      'revert', // 执行 git revert 打印的 message
    ]],
  }
};

package.json 文件

{  
  "commitlint": {
    "extends": ["@commitlint/config-conventional"]
  }
}

husky 配置

旧 husky 配置，我试了下好像没啥效果, 可以使用下面新的配置

package.json 文件

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

新的 husky 配置

Active Hooks

执行下面命令会生成一个 .husky 文件夹

npx husky install

Add Hooks

向 .husky 文件那添加内容

npx husky add .husky/commit-msg 'npx --no-install commitlint --edit $1'

Conventional-changelog-cli (自动生成 CHANGELOG 文件信息)

安装

npm install -g conventional-changelog-cli

命令配置与执行

将命令配置到 package.json 文件 script 中

{
  "scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
  }
}

执行 npm run changelog,可以自动生成 CHANGELOG.md 文件

npm run changelog

注：在每次执行 npm run changelog 命令自动生成 CHANGELOG.md, 之前需要按 SemVer 规范 更新版本。 否则，会导致增量生成的 CHANGELOG 一直都有之前的 commit 记录。

参考文章：
commitlint 官网
Git Guide
Commit message 和 Change log 编写指南
Git commit message 规范
规范你的 commit message 并且根据 commit 自动生成 CHANGELOG.md

avatar
文章
阅读
粉丝