git commit 是很小的一件事情,但是往往小的事情往往引不起大家的关注,不妨打开公司的 gitlab 上的任一个 repo,查看 commit log,满篇的 update 和 fix,完全不知道这些 commit 是要做啥。
为何要规范Commit Message
- 加快Code Review的过程
- 帮助我们写好release note
- 5年后帮你快速想起来某个分支,tag或者 commit增加了什么功能,改变了哪些代码
- 让其他的开发者在运行
git blame
的时候想跪谢 - 总之一个好的提交信息,会帮助你提高项目的整体质量
Commit Message的作用
格式化的Commit message,有几个好处。
「1. 提供更多的历史信息,方便快速浏览。」
比如,使用 git log <last tag> HEAD --pretty=format:%s
显示上次发布后的变动,每个commit占据一行。你只看行首,就知道某次 commit 的目的。
「2. 可以过滤某些commit(比如文档改动),便于快速查找信息。」
比如,使用命令git log <last release> HEAD --grep feature
仅仅显示本次发布新增加的功能。
「3. 可以直接从commit生成Change log。」
Change Log 是发布新版本时,用来说明与上一个版本差异的文档。规范的msg信息可以使用工具自动生成CHANGELOG文档。
Commit Message要求
- 第一行不超过 50 个字符,使用命令
git log --oneline
的时候就只显示第一行 - 第二行空一行
- 第三行开始是描述信息,每行长度不超过 72 个字符,超过了自己换行,主要是为了阅读方便。
- 描述信息主要说明:
- 这个改动为什么是必要的?要告诉 Reviewers,你的提交包含什么改变。让他们更容易审核代码和忽略无关的改变。
- 这个改动解决了什么问题?
- 会影响到哪些其他的代码?这是你最需要回答的问题。因为它会帮你发现在某个 branch 或 commit 中的做了过多的改动。一个提交尽量只做1,2个变化。
你的团队应该有一个自己的行为规则,规定每个 commit 和 branch 最多能含有多少个功能修改。
- 最好有一个相应 ticket 的链接,带上需求或者功能任务对应的链接,对新人了解或者以后回溯很有帮助。
好的Commit提交
总结来说,一次好的commit就是Message清晰、代码只包含一个小功能。
- 「one thing one commit」
在提交 commit 的时候尽量保证这个 commit 只做一件事情,比如实现某个功能或者修改了配置文件。
请将每次提交限定于完成一次逻辑功能。并且可能的话,适当地分解为多次小更新,以便每次小型提交都更易于理解。
- 「易读」
阅读整个项目代码的时候有时候整个项目通读并不是一个好的方法。我们可以通过 issue 或者 commit 来一点一点分解整个 repo。如果一个 commit 只聚焦在一个点上,那么代码看起来也会比较舒服,顺着 commit 读下来就是当初的开发过程了。
- 「cherry-pick」
cherry-pick 是 git 中的一个非常有用的命令,可以将 commit 从一个分支“拷贝”到另一个分支。如果我的 commit 划分都很清楚,那么 cherry-pick 就会比较轻松。但是如果我的一个 commit 即实现了功能A,又实现了功能B,而我只想要功能A,这就很尴尬了。
- 「Code Review」
review 过别人代码的人都知道如果 commit 乱七八糟那将有多么痛苦。
Commit Message的格式
Commit msg的格式可以根据公司的情况来定义,在代码提交时做verify判断格式是否正确,如果只是约定格式而没有校验手段的话,格式往往成为摆设。
我们使用的msg格式:[type]:subject
, type 必填,
「commit msg 必须使用以下 type 前缀开头,如果不符合规范,代码将无法入库」
- 「feature」 (new feature for the user, not a new feature for build script)
- 「fix」 (bug fix for the user, not a fix to a build script)
- 「update」 (update feature code,not a new feature)
- 「docs」 (changes to the documentation)
- 「style」 (formatting, missing semi colons, etc; no production code change)
- 「refactor」 (refactoring production code, eg. renaming a variable)
- 「test」 (adding missing tests, refactoring tests; no production code change)
- 「chore」 (updating grunt tasks etc; no production code change)
- 「bump」(a new version)
Git Commit配置
Commit 的格式可能无法记住,我们可以配置git commit
命令进行提示,按照提示要求要标准化我们的Commit Message。
- 修改
~/.gitconfig
,添加
[commit]
template = ~/.gitmessage
- 新建
~/.gitmessage
,内容为
# [type]: subject
# - type: feature, fix, update, docs, style, refactor, test, chore
# - scope: can be empty (eg. if the change is a global or difficult to assign to a single component)
# - subject: start with verb (such as 'change'), 50-character line
#
# body: 72-character wrapped. This should answer:
# * Why was this change necessary?
# * How does it address the problem?
# * Are there any side effects?
#
# footer:
# - Include a link to the ticket, if any.
# - BREAKING CHANGE
#
- 使用
git commit
命令时,我们将看到上文的提示信息,帮助我们更好的书写msg信息。