Git 约定式提交

约定式提交规范是一种基于提交信息的轻量级约定。它提供了一组简单规则来创建清晰的提交历史;这更有利于编写自动化工具。通过在提交信息中描述功能、修复和破坏性变更,使这种惯例与 SemVer 相互对应。

  • 自动化生成 CHANGELOG。
  • 基于提交的类型,自动决定语义化的版本变更。
  • 向同事、公众与其他利益关系者传达变化的性质。
  • 触发构建和部署流程。
  • 让人们探索一个更加结构化的提交历史,以便降低对你的项目做出贡献的难度。

规范

约定式提交[1] 规定了每一条 commit message 的格式:

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

[optional body]

[optional footer(s)]

类型(type)

类型应当使用小写字母,不能为空,后接可选的范围字段和 !,以及必要的冒号和空格。

下为可用的类型列表:

  • build
  • chore
  • ci
  • docs
  • feat
  • fix
  • perf
  • refactor
  • revert
  • style
  • test

范围(scope)

范围字段可以跟随在类型字段后面。范围必须是一个描述某部分代码的名词,并用圆括号包围。

描述(description)

对代码变更的简短总结,不能为空,结尾不写句号。

正文(body)

在简短描述之后,可以编写较长的提交正文,为代码变更提供额外的上下文信息。正文必须起始于描述字段结束的一个空行后。

正文内容自由编写,并可以使用空行分隔不同段落。

脚注(footer)

在正文结束的一个空行之后,可以编写一行或多行脚注。每行脚注都必须包含一个令牌(token),后面紧跟 :<space><space># 作为分隔符,后面再紧跟令牌的值。

脚注的令牌必须使用 - 作为连字符,唯一的例外是 BREAKING CHANGE

脚注的值可以包含空格和换行。

SemVer 的影响

有些提交类型对 SemVer 的版本号有影响:

  1. fix 表示修复了一个 bug,对应语义化版本的 PATCH
  2. feat 表示新增了一个功能,对应语义化版本的 MINOR
  3. BREAKING CHANGE 包含在脚注中,或类型/范围后有一个 !,对应语义化版本的 MAJOR

工具

Gitmoji

Gitmoji[2] 是一项旨在规范和解释在 GitHub 提交消息上使用表情符号的倡议。

VS Code 扩展

在 VS Code 中提交时,Conventional Commits[3] 扩展可以帮助生成提交信息。

Conventional Commits 的界面

GitHub Action

Release Please Action[4] 是一个 GitHub Action,可以根据提交信息自动生成 CHANGELOG 和发布 Release。

Release Please Action 会自动创建发布 PR,包含生成的 CHANGELOG。当 PR 合并时,发布 Release,此时可以执行 CI/CD,将文件上传到 Release 和发布。

Release Please Action 创建的 PR

参考文献

  1. Conventional Commits. [2022-06-28].
  2. gitmoji. [2022-06-28]. (原始内容存档于2022-06-28).
  3. Semantic Versioning. [2022-06-28]. (原始内容存档于2022-06-28).
  4. Release Please Action. [2022-06-28]. (原始内容存档于2022-06-28).

Git 约定式提交
https://blog.zhanganzhi.com/zh-CN/2022/06/ca740262a99f/
作者
Andy Zhang
发布于
2022年6月28日
许可协议