Git: 如何写好 Commit Message

发表于 2017-11-15 分类于 Git Valine：本文字数： 1.9k 阅读时长 ≈ 2 分钟

更高效的使用 Git Commit Message。

写在前面

个人理解的使用 git 最重要的点是：一定要坚持

单一职责提交：一次提交有必要是一个单独的小任务，小到修正一个变量名，只要是一个单独成一个行为的修改，就不应该与其他修改一起提交。
小步提交：随时提交代码，将大的任务拆小，有助于整理思绪，回溯代码。

基于这样的原则使用 git，commit message 才能够发挥出应有的作用。试想以下，如果在写了一天的代码，仅仅做了一两次提交，当需要回退到今天某个时候的某一版代码时，岂不是灾难？
代码一定会有很多修改或者错误的地方，坚持下来的小步提交让人放心修改，大胆试错。

一个普通的 commit message

为了让提交信息更有可读性，最早由 Angular 团队开发了语义化的提交信息写法。

一个语义化 Commit Message 的例子：

feat(config): allow provided config object to extend other configs

1. add service/user config
2. add updated config object comment

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

其格式可以归纳为：

<类型>([影响的范围]): < 简略的描述 >
[正文：本次修改的详情]
[脚注]

关于上面部分的介绍：

类型
- feat：增加新功能。
- fix：修正已有的 BUG。
- 其他：build, chore, ci, docs, style, refactor, perf, test 等。
范围：应当是一个描述修改范围的名词，括号后应该有冒号。
简略描述：对代码变更的简短总结，以空格开头。
正文：多行，为代码变更提供额外的上下文信息，以空格与首行隔开。
脚注：多行，提交的元信息，如：Merge Request,Reviewer,Breaking Change…
其他
- 在首行的 : 号之前加入 ! 号可以强调 BREAKING CHANGE。同时：脚注或者正文中必须包含: BREAKING CHANGE: description

这样做的好处

更清楚的表达变更的内容
使用工具自动化生成 CHANGELOG。
基于提交的类型，自动生成语义化版本号。
触发构建和部署流程（靠脚注和外部工具实现）。

例 1: 一个复杂的 Commit Message

feat(api)!: new api: user-v2

More detailed explanatory text, if necessary.  Wrap it to 
about 72 characters or so. 

Further paragraphs come after blank lines.

- support markdown
- Use a hanging indent

BREAKING CHANGE: isolate scope bindings definition has changed.
    To migrate the code follow the example below:
    Before:
    scope: {
      myAttr: 'attribute',
    }
    After:
    scope: {
      myAttr: '@',
    }
    The removed `inject` was not generaly useful for directives so there should be no code using it.
Closes #123, #245, #992

例 2: 一个用于回滚代码的 Commit Message

1
2
3

revert: feat(user): abandon user api-v3

This reverts commit 667ecc1654a317a13331b17617d973392f415f02

辅助工具、参考资料

Conventional Commits：语义化提交信息的社区网站。
conventional-changelog：一一个从 git 历史中解析出语义化提交信息的工具。
parse-commit-message：解析工具，可以将提交信息的字符串解析成对象。
conform：用在 git 仓库上执行高级 hooks 的工具，也可以跟提交信息配合使用。
standard-version：可以生成版本号和 CHANGELOG 的工具。
commitsar：一个检查提交信息是否符合特定风格的工具。可在 CI 的 Docker 镜像中使用。