Git Commit 规范与配置

清隆

前言

我在平时使用 git 时,都是随意编写提交说明。发现问题时进行版本回退,看着杂乱无章的提交说明,根本搞不清哪一次提交了什么内容,深受其害。

之后在学习过程中,认识到 Commit 规范与配置,总结内容,分享出来。

什么是 Commit message

Git 每次提交代码,都要写 Commit message(提交说明),否则就不允许提交。

git commit -m "hello world"

上面代码的 -m 参数,就是用来指定 Commit message 的。

如果一行不够,可以只执行 git commit,就会跳出文本编辑器,让你写多行。

基本上,你写什么都行。但是,一般来说,Commit message 应该清晰明了,说明本次提交的目的。
image.png

目前,社区有多种 Commit message 的写法规范。本文介绍 Angular 规范(见上图),这是目前使用最广的写法,比较合理和系统化,并且有配套的工具。

Commit message 的作用

格式化的 Commit message,有几个好处。

(1)提供更多的历史信息,方便快速浏览。

比如,下面的命令显示上次发布后的变动,每个 commit 占据一行。你只看行首,就知道某次 commit 的目的。

git log --oneline  

(2)可以过滤某些 Commit(比如文档改动),便于快速查找信息。

比如,下面的命令仅仅显示本次发布新增加的功能。

git log --grep feature

(3)可以直接从 Commit 生成 Change log。

Change Log 是发布新版本时,用来说明与上一个版本差异的文档,详见后文。

Commit message 格式

每次提交,commit message 都包括三个部分:Header,Body 和 Footer。其中,Header 是必需的,Body 和 Footer 可以省略。

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

Header

Header 部分只有一行,包括三个字段:type(必需)、scope(可选)和subject(必需)。

不管是哪一个部分,任何一行都不得超过72个字符(或100个字符)。这是为了避免自动换行影响美观。

type

type 用于说明提交的类别

  • 主要type

    • feat:新功能(feature)
    • fix:修补bug
  • 特殊type

    • docs:只改动了文档相关的内容(documentation)
    • style:代码格式(不影响代码运行的变动)
    • build:构造工具的或者外部依赖的改动,例如webpack,npm
    • refactor: 代码重构时使用
    • revert: 执行git revert打印的message
  • 较少使用type

    • perf:性能优化(Performance improvement)
    • test:测试方便的改动
    • ci:与持续集成服务有关的改动
    • chore:不修改src或者test的其余修改,例如构建过程或辅助工具的变动

scope

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

subject

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

Body

Body 部分是对本次 Commit 的详细描述,可以分成多行。

Footer

Footer 部分只用于两种情况。

  • 不兼容变动

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

  • 关闭 Issue

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

    Closes #234

    也可以一次关闭多个 issue 。

    Closes #123, #245, #992

Revert

Revert 是一种特殊情况,用于撤销以前的 Commit。其必须以revert:开头,后面跟着被撤销 Commit 的 Header。

revert: feat(pencil): add 'graphiteWidth' option

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

Body 部分的格式是固定的,必须写成 This reverts commit commit_id

Change log

Change Log 是发布新版本时,用来说明与上一个版本差异的文档,一般包含 "Feature","Fix","Performance Improvement"与"Breaking Changes"。

如果你的所有 Commit 都符合 Angular 格式,那么发布新版本时,Change log 就可以用脚本自动生成,方法如下:

全局安装 conventional-changelog-cli

npm install -g conventional-changelog-cli@2.2.2

在你的项目根目录中执行

conventional-changelog -p angular -i CHANGELOG.md -s

不会覆盖任何以前的变更日志。只会在 CHANGELOG.md 的头部加上自从上次发布以来的变动。

如果你是第一次使用并且你想生成所有以前的更改日志,可以执行

conventional-changelog -p angular -i CHANGELOG.md -s -r 0

这将覆盖任何以前的更改日志。

/*
 * 配置项说明:
 * -p angular 指定风格
 * -i CHANGELOG.md 指定输出的文件名称
 * -s 指定增量更新,不会覆盖以前的更新日志
 * -r 0 从最新的版本生成多少个版本的日志,如果为0,则日志将重新生成。
 */

你可以在项目配置文件 package.json 中添加脚本以简便操作。

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

生成日志如下图:
image.png

配置 Commit 规范

格式化规范工具 Commitizen

可以利用 Commitizen,帮助我们撰写规范的提交信息,方法如下:

安装 commitizencz-customizable

npm install -g commitizen@4.2.4
npm install -D cz-customizable@6.3.0 

package.json 中进行新增

"config": {
  "commitizen": {
    "path": "node_modules/cz-customizable"
  }
}

在根目录下新建 .cz-config.js 文件并写入配置

module.exports = {
  // 可选类型
  types: [
    { value: 'feat', name: 'feat:     新功能' },
    { value: 'fix', name: 'fix:      修复' },
    { value: 'docs', name: 'docs:     文档变更' },
    { value: 'style', name: 'style:    代码格式(不影响代码运行的变动)' },
    { value: 'refactor', name: 'refactor: 重构' },
    { value: 'perf', name: 'perf:     性能优化' },
    { value: 'test', name: 'test:     增加测试' },
    { value: 'chore', name: 'chore:    构建过程或辅助工具的变动' },
    { value: 'revert', name: 'revert:   回退' },
    { value: 'build', name: 'build:    打包' },
    { value: 'ci', name: 'ci:       与持续集成服务有关的改动' },
  ],
  // 消息步骤
  messages: {
    type: '请选择提交类型:',
    customScope: '请输入修改范围(可选):',
    subject: '请简要描述提交(必填):',
    body: '请输入详细描述(可选):',
    footer: '请输入要关闭的issue(可选):',
    confirmCommit: '确认使用以上信息提交?(y/n/e/h)',
  },
  // 跳过问题
  skipQuestions: ['footer'],
  // subject文字长度默认是72
  subjectLimit: 72,
}

之后就可以用 git cz 来代替 git commit

git cz   
cz-cli@4.2.4, cz-customizable@6.3.0

All lines except first will be wrapped after 100 characters.
? 请选择提交类型: (Use arrow keys)
> feat:     新功能
  fix:      修复
  docs:     文档变更
  style:    代码格式(不影响代码运行的变动) 
  refactor: 重构
  perf:     性能优化
  test:     增加测试
? 请输入修改范围(可选):
? 请简要描述提交(必填): 新功能xxx
? 请输入详细描述(可选):      
? 请输入要关闭的issue(可选):

###--------------------------------------------------------###
feat: 新功能xxx
###--------------------------------------------------------###

? 确认使用以上信息提交?(y/n/e/h)
  • cz-customizable 是一款shell插件,无法在 git bash 中正常使用

使用 Husky 强制执行规范

只是我们自己遵守规范是不够的,要让项目的所有开发者,都强制遵守此规范,可以通过 Commitlint 与 Husky 来实现,方法如下:

安装 commitlint/clicommitlint/config-conventional

npm install -D @commitlint/config-conventional@12.1.4 @commitlint/cli@12.1.4

添加 commitlint 的配置文件 commitlint.config.js 并写入配置

module.exports = {
  // 继承的规则
  extends: ['@commitlint/config-conventional'],
  // 定义规则类型
  rules: {
    // type 类型定义,表示 git 提交的 type 必须在以下类型范围内
    'type-enum': [
      2,
      'always',
      [
        'feat', // 新功能 feature
        'fix', // 修复 bug
        'docs', // 文档注释
        'style', // 代码格式(不影响代码运行的变动)
        'refactor', // 重构(既不增加新功能,也不是修复bug)
        'perf', // 性能优化
        'test', // 增加测试
        'chore', // 构建过程或辅助工具的变动
        'revert', // 回退
        'build', // 打包
        'ci', // 与持续集成服务有关的改动
      ],
    ],
    // subject 大小写不做校验
    'subject-case': [0],
  },
}

安装 husky

npm install -D husky@7.0.1

初始化 husky

npx husky install

将 husky 与commitlint 进行关联,执行

npx husky add .husky/commit-msg

在生成的 commit-msg 文件中写入指令 (替换undefined)

npx --no-install commitlint --edit

这样子就配置完成了,进行不符合规范的提交时,命令行就会报错

git commit -m 'hello world'
⧗   input: hello world
✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

✖   found 2 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

husky - commit-msg hook exited with code 1 (error)

只有攥写符合规范的提交说明,才能成功提交

git commit -m 'feat: 新功能xxx'
[master 84d6807] feat: 新功能xxx
 3 files changed, 12 insertions(+), 6 deletions(-)
 delete mode 100644 .husky/pre-commit

结语

如果文中有错误或不严谨的地方,请务必给予指正,十分感谢。

如果喜欢或者有所启发,欢迎点赞关注,鼓励一下新人作者。

内容参考自:

Commit message 和 Change log 编写指南

commIt type - CSDN

commit 规范配置教程

阅读 694

学完某项技能一定要写写文章,用的时候都是照搬代码,写出来才能深入理解!

10 声望
0 粉丝
0 条评论

学完某项技能一定要写写文章,用的时候都是照搬代码,写出来才能深入理解!

10 声望
0 粉丝
文章目录
宣传栏