Git Commit 范式

Git Commit Conventions

5 min read

每次提交代码时,都需要编写 Commit Message。

git commit -m "hello world"

Commit Message 应当尽可能多的提供有用的信息,指明本次提交的目的。同时又应当简洁明了,便于阅读以及日后追踪问题。

但对于自然语言来说,同时满足“更多的信息”和“简洁明了”是个不小的挑战。

因此规范化 Commit Message 的是个不错的选项,特别是对于团队协作来说更是必要。

规范化 Commit

大体来说,一个规范的 Commit 可以分为三个部分:Header、Body 和 Footer。

并且每个部分间都需要用一个空行分隔。像这样:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

除非他是一个回滚提交 (Revert Commit)

Header 部分是最基本也是最重要的。

<type>[optional scope]: <description>

Header 又可以分为三个部分:typescopedescription,其中只有 typedescription 是必须的。

type

type 的作用是描述这次提交的类型,例如 feat 表示这次提交的作用是增加一个 (或数个) 新特性 (Feature),fix的作用一般是修复 bug…

根据 Angular 项目的 Commit 规范type 有且只有以下取值:

  • build: 影响构建或外部依赖项的更改 (gulpbroccolinpm…)
  • ci: 对 CI 配置文件和脚本的更改 (Circle, BrowserStack, SauceLabs…)
  • docs: 修改文档
  • feat: 增加一个新的特性 (feature)
  • fix: 修复一个 bug
  • perf: 提到性能的代码更改
  • refactor: 既不修复错误也不添加功能的代码更改 (代码格式优化,重构等)
  • test: 添加或修改测试

scope

scope 不是必须的,它必须配合 type 使用,作用是描述这次提交影响的范围。例如:

build(npm): add dependency XXX
docs(readme): update README.md
docs(changelog): update CHANGELOG.md

description

description 就正如其名,是对此次提交的一句简单的描述,使用祈使句,现在时 (例如:使用 “change”,而不是 “changed” 或 “changes”),一般不超过 50 个字符。不要以大写开头,并且结尾不写标点符号。

description 不要以大写开头!!

Body

虽然是非必须的,但如果能写还是尽量要写。其作用是对 description 的补充或展开,更为详细的解释进行更改动机和原因。

你可以将先前行为与新行为进行比较,以说明更改的影响。

description 一样,使用祈使式,现在时 —— 使用 “fix”,而不是 “fixed” 或 “fixes”。

Footer 可以包含有关重大更改的信息 (例如不兼容的更改等),同时也是引用或关闭 GitHub issues、Jira tickets、其他 PRs 和其他提交的地方。

BREAKING CHANGE: <breaking change summary>

<breaking change description + migration instructions>

Fixes #<issue number>

不兼容的更改必须以 BREAKING CHANGE: 开头,其后为对不兼容更改的简短的描述,(空一行后的) 详细的描述,以及迁移指南等。

Revert

众所周知,只有鸡啄完米,狗舔完面,火烧断锁,甲方 (产品经理) 才不会改需求。所以我们时常需要不得不回滚到某次提交。这时你应该使用回滚提交 (Revert Commit)。

回滚提交 (Revert Commit) 是一种特殊的提交,它强制以 revert: 开头,其后是需要被回滚到的提交的 Header

其提交消息的 Body 部分应包含:

  • 以下格式描述的需要被回滚到的提交的 SHA 的信息:This reverts commit <SHA>,
  • 对回滚提交的原因的清晰描述。
revert: <Header of the reverted commit>

This reverts commit <SHA of the reverted commit>

<description of the reason for reverting>

参考