Git Commit Message Style

Iceyer edited this page Jan 31, 2018 · 7 revisions

Git 提交日志编写规范

如何编写优秀的 commit 信息?

基本格式

注意: commit 信息必须使用英文进行编写。

简单的描述下这个commit改变了什么。(不超过 50 个字.若隶属某个模块可以使用模块名+':'的形式)
<若有正文则此处*必须*空一行>

如果有更细致的描述就写在这里。每一行不要超过 72 个字。
这里应该描述为什么要这样做以及是如何

<若正文需要可以选择空行>
正文内容可以使用 ‘-’,‘**’ 等非常通用的标记。但标题中不允许出现。

Resolves: bug 描述的具体地址。元信息可以不遵循 72 字 wrap 的规定
<元信息需要使用空行分离>
See also:
- 若有多个链接则采用多行See also: 的形式进行表达
- 其他 CL 链接或 bug 链接
- 对某些功能或 bug 有影响的链接

关于链接有两点需要注意

  1. 应使用可以直接访问到的地址。不可以是一个 bugid 或 CL id 号
  2. 链接的访问权限不应该高于此 commit 的访问权限。简单的说就是能看到 commit 的人也需要可以访问到 commit 中的链接 (未解决tower问题前此处不限制tower任务)

基本原则

”基本格式“看起来非常简单。但仅仅达到基本格式的要求依旧写不出好的 commit。但只要我们遵循以下 7 条原则,基本很难 写出差的commit。更详细的参考资料 7条原则

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how

第 3,4 条,说的是一个简单的事实:第一行是标题,标题首字母大写,标题不是句子不需要句号。

第 5 条,使用祈使句非常非常重要。简单的说,第一个动词用原型,不要 使用 ing 或 ed 的形式。

第 7 条,重点描述做了什么以及为何要这样做而不是那样做。代码的 diff 会告诉后来者你选择的方式是怎么做的。但代码无法记录做这个 change 时 候的决策。

推荐玩法

遵循 7 条基本原则后的 commit 已经看上去不错了。但还有很多方式可以 让我们更容易更自然的写出优秀的 commit

  • 不要使用 git commit -m <msg> 让编辑器来保障你不会犯丢人的错误吧。
  • 在 commit 的编辑器中开启拼写检查。伙计,全世界都盯着在,像你这么厉害的人不想被人翻老底吧。
  • 使用 git add -p 或者 magit 来方便快捷的对一个文件的部分区域 进行提交。绝大多时候写不出第一行就是因为一次提交过多了。让你的 commit 更加原子性吧。
  • 使用 Angular Commit Message Format, 可以方便使用clog工具生成CHANGELOG.md. 参考: Generate CHNAGELOG.md with clog
  • 参考动词 (可参考 jenkins的changelog)
    • Fix
    • Release
    • Change
    • Remove
    • Add
    • Implement
    • Enable
    • Improve
    • Refactor
    • Update
    • Make
    • Reduce

参考文档

  • https://github.com/erlang/otp/wiki/Writing-good-commit-messages
  • http://git-scm.com/book/ch5-2.html
  • http://www.freshconsulting.com/atomic-commits/
  • https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message
  • https://news.ycombinator.com/item?id=10212582
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.