Git 约定式提交规范实践

约定式提交规范 提供了一个轻量级的提交历史编写规则，它的内容十分简单：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

举个简单的例子：

feat(config): 允许 config 对象直接从其他 config 继承

BREAKING CHANGE: 在 config 对象中增加 `extends` 字段，用于从其他继承 config

close issue #23

在 git commit 时，如果你想进行多行 commit 编辑，可以通过 git commit -a 进入编辑界面；如果是单行，可以直接 git commit -a -m 'COMMIT MESSAGE' 完成提交。

更多的约定

约定式规范与 SemVer 的设计是相吻合的，

PATCH -> type(fix)
MINOR -> type(feat)
MAJOR -> BREAKING CHNAGE

大部分的提交中，我们都会使用 fix 和 feat 来描述本次修改的类型，当然也包含其他类型，如 chore/docs/reflector/improvement/perf/test/style ，值得注意的是：

• 一般不用写 body 部分的内容，除非存在 BREAKING CHANGE
• description 的内容要相当简明扼要，用简单的语句把修改点直接说出来
• 一般不建议将多次修改放在一次提交中，尤其是一次半（第二个修改只完成了一部分）的情况
• scope 可以是一个文件的地址，如 /lib/utils ；也可以是某个功能点 parser ，不建议超过两个单词

一些技巧

合并多次提交

如果你上次修改的内容存在 bug 或未完成，本次提交的内容与上次几乎一样，建议使用 git rebase -i 进行提交的合并，如

git rebase -i HEAD~3 # 展示最近 3 次修改

输出如下：

pick 0291959 chore(blog): 清理无关项
pick 1ef8f31 chore(blog): 清理无关项
pick 36a91db fix(post): 格式化 post 的 meta 数据格式,增加 --- 开始符

可以将第二行的 pick 修改为 squash ，表示保留 commit 但将本次修改合并到上次，相关的操作可以看这篇文章。

关闭 ISSUE

在 github/gitlab 中，如果 commit message 中带有 Fix #23 诸如此类的信息，当 commit 被 push 到 repo 后，会自动关闭编号为 23 的 issue。

自动生成 CHANGELOG

在写日报或者周报，或者在项目发版时，我们可以很轻松地从提交日志中看到自己或者团队干了些什么事情：

alias git-changelog='git log --oneline --decorate';

当然也可以使用开源的工程自动生成结构化更强的 CHANGELOG 日志，如 auto-changelog ，它提供了可自定义的 CHANGELOG 模板。

项目配置

约定如果没有工具来辅助和约束，大概率就成了一纸空文，毫无意义。在项目实战中，我们可以做如下配置让项目成员强制进行约定式提交。

1. 安装工具

推荐使用 @commitlint/cli 进行检测，安装方式：

npm install @commitlint/cli --save-dev

2. 配置约定

在 @commitlint 工具包中有一个规则比较强的检测规范： @commitlint/config-conventional ，也安装到项目中：

npm install @commitlint/config-conventional --save-dev

安装完成后，需要显式地配置，在项目中增加 commitlint.config.js ：

module.exports = { 
  extends: [
    '@commitlint/config-conventional'
  ] 
};

config-conventional 中允许类型有 build/chore/ci/docs/feat/fix/perf/refactor/revert/style/test 。

3. 提交时执行检查

推荐使用 husky 这个工具，它会帮助我们自动配置 commit hooks，只需在项目中添加 .huskyrc.json 文件：

{
  "hooks": {
    "pre-commit": "node ./node_modules/@commitlint/cli/lib/cli.js -E HUSKY_GIT_PARAMS"
  }
}

当然也可以直接在 package.json 中配置 husky 字段，具体可以查看 文档 。

小结

整洁的提交记录并不仅仅意味着开发者自动生成 CHANGELOG，遵守约定可以给项目沉淀一个结构化的提交历史，再加上一些 emoji，生成出来的文档简直就是一篇生动的项目发展史，它有助于我们向公众传达变化的性质，同时对继续集成也会带来一定的好处，比如我们可以根据 type 触发不同的构建和部署流程。