6

Git: 如何写好 Commit Message

 2 years ago
source link: https://ppzz.github.io/posts/191d/
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
neoserver,ios ssh client

Git: 如何写好 Commit Message

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

更高效的使用 Git Commit Message。

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

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

基于这样的原则使用 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

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 镜像中使用。

report

Recommend

About Joyk


Aggregate valuable and interesting links.
Joyk means Joy of geeK