UP | HOME

好好吃饭，好好 commit

Table of Contents

我在新介入一个项目的时候，一般会习惯 tig (一款优秀的 git 命令行可视化工具) 一下，浏览一下项目最近活跃的提交，去大体了解一下 这个项目最近在干什么事情，解决了哪些问题。如果项目中的 commit message 写的规范清晰，风格统一的话，我们就可以直观的感受到每次提交都 干了哪些事儿。但有时候，如果团队没有一个统一且严格的准则来指导编写 commit message，我们可能会看到很多非常简略的 commit message，如 fix 、 fix bug 、 update 、 修复订单bug 等, 这种无法准确传达意图的描述，往往会在问题排查，代码阅读等场景下给我们造成困扰，所以，编写规范统一的 commit message 其实是非常重要的，而很多时候这一点往往被忽视了。

为什么要好好写 commit message？

任何一个项目或者软件都是需要协作的项目，最少也会包含两个开发者，原作者和几周或者几个月之后的原作者，或许下面的场景在你身上也发生过，排查问题或者优化代码时，发现代码写的很垃圾，刚要骂*的时候【脾气急的同学可能已经骂完了（逃…】，一查提交历史发现是自己过去一段时间所写的。所以，协作过程中写好 commit message，基于以下几点原因:

  • 更好的表达代码意图
  • 加速 code review 速度
  • 基于一定准侧的情况下，可以快速筛选特定的 commit message
  • 帮助新同学或者未来的自己，快速建立上下文

如何写出好的 commit message？

一条好的 commit message 需要回答三个问题：

  • 提交为何是必要的？
  • 是如何解决问题的（针对一些修复类的提交）
  • 会产生哪些影响？

格式

commit message 的格式我们可以参考业界比较优秀的一些例子，比如 AngularJS 的 Commit Message Guidelines

commit-message.png

整体格式为： 

<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>
  • type (must): 上图中列出的类型比较通用，我们可以直接使用，同样也可以结合自己的业务，整合一些定制化的类型，补充进去。
  • scope (建议must) : 范围上相对灵活，只需要表明本次提交影响的范围即可。
  • subject (must): 主题编写对此次提交的总结性描述，不要超过50个字。以动词开头，使用祈使句，如使用 change sth，而不是changed sth; 不要使用标点符号结尾，因为这其实是标题。
  • body ：与 subject 之间必须有空行隔开，每行最好不超过 72 个字, 避免自动换行影响美观。
  • footer ：footer 一般用的比较少，主要用在一些不兼容的版本变动和关闭issue时。

给出一个截止到发文日，AngularJS最新的一次 commit 示例： 

chore(ci): correctly compute `$DIST_TAG` in the `deploy-code` CI job

Previously, the `DIST_TAG` environment variable was failing to be
computed correctly in the `deploy-code` CI job, because it relied on the
non-existent `node` executable. It worked with the default executor
(which includes `node`), but not with the `cloud-sdk` executor used in
`deploy-code`, resulting in the following error:

```sh
./.circleci/env.sh: line 59: node: command not found
DIST_TAG=
```

You can see an example failure in the "Set up environment" step logs in
https://app.circleci.com/pipelines/github/angular/angular.js/
170/workflows/32fcacf9-c89b-4020-b3eb-15debe18bb67/jobs/1793

This commit fixes it by computing `$DIST_TAG` using unix tools (`cat`,
`grep`, `sed`) that _are_ available on the docker images of all
executors.

Closes #17067

注意事项

  • 不要将不同的修改合并在一次 commit 中提交
  • 适当折叠 commit，安装 brew install nvie/tap/git-toolbelt ，使用 git fixup ，替代 git commit --amend
  • 一些空行、空格的添加和修改，不要和代码混在一起提交
  • 不要搞超大的提交，小步快跑，每次提交只完成一件事
  • 需要制定一些所有成员都必须遵守的团队规则，保证整个项目风格统一

哪有时间写那么详细的 commit message，还干活吗？

在项目的整个生命周期内，我们书写的每一个行代码都在构建项目的历史，而 commit message 在一定程度是历史的缩影，就像历史书籍中的目录，完整的历史脉络可以帮助后人更好的理解历史，代码亦是如此；我们在思考编写 commit message 的时候，其实更是一次自我检验的机会，书写过程中我们可以思考本次commit是 否有一些可以优化的点 、*是否有未完成的todo* 、*是否掺杂了无关的代码* 等。不要将编写清晰明确的 commit message 当做是一种负担，这是一名合作的协作者应该具备的能力，也应该是一个享受的过程。

Enjoy it! Cause you are making history.

reference