Git约定式提交规范

约定式提交是一种用于对Git的提交信息的轻量级规范,其创造了一套构建明确的提交历史信息的规则,不仅方便向他人传达变化的性质,而且对构建自动化工具非常友好。

完整的规范可以在这里阅读,目前(2021年7月)最新的是v1.0.0版本。以下是简单的摘录。

基本介绍

提交信息满足以下结构:

1
2
3
4
5
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

type表示本次提交的分类,约定如下:

  1. fix: 修复了一个bug(这和语义化版本中的 PATCH 相对应)
  2. feat: 新增了一个功能(这和语义化版本中的 MINOR 相对应)
  3. BREAKING CHANGE: 在脚注中包含 BREAKING CHANGE:<type>[optional scope] 后面有一个 ! 的提交,表示引入了破坏性 API 变更(这和语义化版本中的 MAJOR 相对应)。 破坏性变更可以是任意 type 的提交
  4. 另外,除 fix:feat: 之外,也可以使用其它提交 类型 ,例如 @commitlint/config-conventional(基于 Angular 约定)中推荐的 build:chore:ci:docs:style:refactor:perf:test:,等等。这些类型对应的使用场景分别为
    • build: 影响构建系统或外部依赖的修改,例如 npm
    • chore: 不涉及到生产代码的配置文件的修改,某种程度上包含 build:ci: 的含义,个人更倾向于用 chore:
    • ci: CI配置文件或脚本的修改
    • docs: 文档相关修改
    • style: 不涉及到生产代码含义的修改,例如空格、缩进、格式、分号等
    • refactor: 既没修复bug又没添加功能的重构修改,例如重命名变量等
    • perf: 提升性能的修改
    • test: 有关测试相关的代码的修改
  5. 脚注中除了 BREAKING CHANGE: <description>,其它条目应该采用类似 git trailer format 这样的惯例

其它提交类型在约定式提交规范中并没有强制限制,并且在语义化版本中没有隐式影响(除非它们包含 BREAKING CHANGE)。 可以为提交类型添加一个围在圆括号内的范围,以为其提供额外的上下文信息。例如 feat(parser): adds ability to parse arrays.。

示例

包含了描述并且脚注中有破坏性变更的提交说明

1
2
3
feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

包含了 ! 字符以提醒注意破坏性变更的提交说明

1
refactor!: drop support for Node 6

包含了 ! 和 BREAKING CHANGE 脚注的提交说明

1
2
3
refactor!: drop support for Node 6

BREAKING CHANGE: refactor to use JavaScript features not available in Node 6.

不包含正文的提交说明

1
docs: correct spelling of CHANGELOG

包含范围的提交说明

1
feat(lang): add polish language

包含多行正文和多行脚注的提交说明

1
2
3
4
5
6
7
8
fix: correct minor typos in code

see the issue for details

on typos fixed.

Reviewed-by: Z
Refs #133