写一个体验良好的git commit

Posted 2020-11-19 chris.wu

一直在使用git也看过格式各样commit log , review 代码时最刺激的是看到这类 “.” 应付差事，还有 "fix bug"，"fix" 等等

沟通五何原则

简单介绍下沟通的“五何原则”，因为commit log 是写给自己和团队其他成员看的，需要认真对待，前期debug没时间想清楚commit log , 后期任务完成也可以压缩多个提交为一个，单个提交可以使用 --amend 来修改等等，进入正题就是沟通的时候要跟别人讲清楚

• 何时
• 何地
• 因何故
• 需要何人
• 做何事

这个原则我觉的可以借鉴和发散一下应用到commit log 上，何时（在什么时间点log上有），何地（关联修改了哪些，文件，影响哪些功能），因何故（修改bug,代码重构，新需求开发），需要何人（引入了哪些外部资源），做何事（把本次提交主要解决了什么问题描述清楚）

我常用前缀命名

我也反思过怎么样子写一个自己看着舒服，有一定命名约定的commit,以下是我自己经常用到的前缀Action描述，借鉴阮一峰老师的思路，希望可以抛砖引玉

Debug : 正在对一个文件进行调试，中间在修改
Done : 结束debug,或是重构，完成了进行中的活动
Trim : 表示对一个文件进行整理：空格，函数位置，缩进
Init : 新建分支，会写一个描述，如有任务，附带任务的链接
Fix : fix bug
Mod : remove unused code, 表示修改（Modify）
Add : a new module to have faster process, 表示新增（Add）
Rem : deprecate unused modules, 表示移除（Remove）
Ref : improved the implementation of module X, 表示重构（Refactory）
Branch : 新分支的建立
Dev : 新功能开发中
Merge : 分支合并

我经常使用的commit格式

commit 947c4962a1013005969e934a66c70d2b52dbb132
Author: buoge <[email protected]>
Date:   Thu Jun 7 16:24:58 2018 +0800

    Mod: CpaReportDaiy activated_at as report_date filter is null

commit b3ccb225d806c5e7d0fa8a536a12b7a41951b67f
Author: buoge <[email protected]>
Date:   Thu Jun 7 14:38:00 2018 +0800

    Fix: user registe num count bug when can not get idfa and return 0000*

commit 379e316620addc8b3db1d01595a97053300eacb5
Author: buoge <[email protected]>
Date:   Wed Jun 6 18:06:15 2018 +0800

    Debug: CpaReportDaiy_v2

commit 362bf11b450675120ef5400130e68398848e694f
Author: buoge <[email protected]>
Date:   Wed Jun 6 16:39:40 2018 +0800

    Ref: genUserReport to aggregateUserReport

commit ec061ad3b385209de0e5efb292d8b64596f3559e
Author: buoge <[email protected]>
Date:   Wed Jun 6 16:29:09 2018 +0800

    Mod: CpaReportDaiy_v2, generateUserReport new aggregation algorithm

推荐使用的格式：

• 第一行应该少于50个字。 随后是一个空行 第一行题目也可以写成：Fix issue #8976

• 永远不在 git commit 上增加 -m

  一个不好的例子 git commit -m "Fix login bug"

一个推荐的 commit message 应该是这样：

    Redirect user to the requested page after login

    https://trello.com/path/to/relevant/card

    Users were being redirected to the home page after login, which is less
    useful than redirecting to the page they had originally requested before
    being redirected to the login form.

    * Store requested path in a session variable
    * Redirect to the stored location after successfully logging in the user

注释最好包含一个连接指向你们项目的issue/story/card
一个完整的连接比一个 issue numbers 更好提交信息中包含一个简短的故事，能让别人更容易理解你的项目注释要回答如下信息

为什么这次修改是必要的？
要告诉 Reviewers，你的提交包含什么改变。让他们更容易审核代码和忽略无关的改变。

• 如何解决的问题？**
  这可不是说技术细节。看下面的两个例子：

Introduce a red/black tree to increase search speed
Remove

这些变化可能影响哪些地方？

这是你最需要回答的问题。因为它会帮你发现在某个 branch 或 commit 中的做了过多的改动。一个提交尽量只做1，2个变化。

• 你的团队应该有一个自己的行为规则，规定每个 commit 和 branch 最多能含有多少个功能修改。

小提示

使用 fix, add, change 而不是 fixed, added, changed
永远别忘了第2行是空行
用 Line break 来分割提交信息，让它在某些软件里面更容易读
请将每次提交限定于完成一次逻辑功能。并且可能的话，适当地分解为多次小更新，以便每次小型提交都更易于理解。

Examples of good practice：

范例一：

Fix bug where user can‘t signup.

[Bug #2873942]

Users were unable to register if they hadn‘t visited the plans
and pricing page because we expected that tracking
information to exist for the logs we create after a user
signs up.  I fixed this by adding a check to the logger
to ensure that if that information was not available
we weren‘t trying to write it.
Redirect user to the requested page after login

https://trello.com/path/to/relevant/card

Users were being redirected to the home page after login, which is less
useful than redirecting to the page they had originally requested before
being redirected to the login form.

* Store requested path in a session variable
* Redirect to the stored location after successfully logging in the user

范例二：

    commit 3114a97ba188895daff4a3d337b2c73855d4632d
    Author: [removed]
    Date:   Mon Jun 11 17:16:10 2012 +0100

    Update default policies for KVM guest PIT & RTC timers

    The default policies for the KVM guest PIT and RTC timers
    are not very good at maintaining reliable time in guest
    operating systems. In particular Windows 7 guests will
    often crash with the default KVM timer policies, and old
    Linux guests will have very bad time drift

    Set the PIT such that missed ticks are injected at the
    normal rate, ie they are delayed

    Set the RTC such that missed ticks are injected at a
    higher rate to "catch up"

    This corresponds to the following libvirt XML

      <clock offset=‘utc‘>
        <timer name=‘pit‘ tickpolicy=‘delay‘/>
        <timer name=‘rtc‘ tickpolicy=‘catchup‘/>
      </clock>

    And the following KVM options

      -no-kvm-pit-reinjection
      -rtc base=utc,driftfix=slew

    This should provide a default configuration that works
    acceptably for most OS types. In the future this will
    likely need to be made configurable per-guest OS type.

    Closes-Bug: #1011848

    Change-Id: Iafb0e2192b5f3c05b6395ffdfa14f86a98ce3d1f

• 补充一个相关的链接：
  “如何优雅的使用git：”
  http://blog.waterstrong.me/master-git/

• http://www.ruanyifeng.com/blog/2016/01/commit_message_change_log.html

• commit log 不是万能的, 不看代码改动是万万不能的，最终代码评审还是要看代码改动来检查和确认，一个简明扼要的log能提高这个的效率