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