增進工程師效率 – Git and Log File

by allenlu2007

Reference:

[1] Chris Beams, “How to Write a Git Commit Message

[2] Louis_Lu’s Blog, “如何寫一個 Git Commit Message” 

[3] M. Hung, “撰寫有效的 Git Commit Message

[4] Gitconfig example

 

 

 

前言

在軟體開發中,Git 是一個版本控管工具。為什麼以及如何使用 git 可見多文。

雖然有很多 IDE Git tool, command line 仍然是最方便以及最 powerful tool.

為了節省打字時間,可以事先定義 shorthand 於 .gitconfig.

 

本文聚焦在如何撰寫 git commit message (GCM) 以及如何顯示 GCM.  坦率的說,大多數人寫的 GCM 不容易看懂。Quality 不好的 GCM 基本讓 git 白做工。以下為例:

Git commit 2x

[1] 的 before and after GCM 如下。

Before:

NewImage

After:

NewImage

你覺得哪種看起來比較舒適?

前者無論是在長度或結構上都很糟;後者則是簡明與一致的。前者是大部份情況下會發生,後者從不會自動發生。

大部分 repos 的 GCM 都跟前者差不多,但還是有例外的情況。可以參考 Linux kernel 以及 Git 本身,都是一個很好的範例。再看看 Spring Boot,或是任何由 Tim Pope 維護的 repos。

這些 repos 的貢獻者知道一個精心打造的 Git commit message 是跟其他開發者 (以及未來的自己) 講解關於一個改變的脈絡 (communicate context about a change) 的最好方式。一個 diff 可以告訴你什麼改變了,但是只有 commit message 可以正確的告訴你為什麼 。

如果你對於什麼樣的內容造就一個好的 GCM 沒有太多的想法,這大概是因為你沒有花很多時間使用 git log 以及相關的指令。這會產生一個糟糕的循環:因為 commit 歷史是不一致且沒有架構的,你就不會花時間使用它或是維護它。而因為它沒有被使用或是被維護,就會一直是不一致且沒有架構的狀況。

但是一個精心撰寫的 log 是漂亮以及有用的。git blame、revert、rebase、log、shortlog 以及其他相關的指令會進入到你的生活中。檢閱其他人的 commits 以及 pull requests 變成一個值得去做的事情,並且變得可以獨立完成。我們因此變得能夠理解一件數個月前或數年前的事情。

 

Git commit message 的七大規則

  1. 用一行空白行分隔標題與內容
  2. 限制標題最多只有 50 字元
  3. 標題開頭要大寫
  4. 標題不以句點結尾
  5. 以祈使句撰寫標題
  6. 內文每行最多 72 字
  7. 用內文解釋 what 以及 why vs. how

舉例而言:

NewImage

 

1 用一行空白行分隔標題與內容

git commit 的 manpage 這樣寫到:

Though not required, it’s a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used throughout Git. For example, Git-format-patch(1) turns a commit into email, and it uses the title on the Subject line and the rest of the commit in the body.

首先,不是所有的 commit message 都同時需要標題與內文。有時候一行文也很好,尤其是改變很簡單,以致於不需要進一步的脈絡敘述。例如說:

NewImage

實在沒什麼需要再說的了;如果讀者想要了解是什麼樣的 typo,他可以自己看。例如說使用 git show 或是 git diff 或是 git log -p 等等。

如果你要做這樣的 commit 的話,可以在 git commit 使用 -m 選項:

NewImage

然而,當你的 commit 需要一點解釋以及脈絡的時候,你需要撰寫內文。舉例來說:

NewImage

Commit messages 有內文的時候,使用 -m 選項會很難撰寫。你可能會需要適當的文字編輯器來撰寫。如果你還沒有設定好相關的文字編輯器,請閱讀 Pro Git 的這個章節。

在任何情況下,標題與內文的分隔會在瀏覽 log 的時候看出。以下是一個完整 log 的 entry:

NewImage

現在使用 git log –oneline 命令,將只會印出其標題:

NewImage

或是使用 git shortlog,將 log 以使用者群組起來,並且只會簡潔的列出標題:

NewImage

There are a number of other contexts in Git where the distinction between subject line and body kicks in—but none of them work properly without the blank line in between.

 

2. 限制標題最多只有 50 字元

50字元的限制不是一個硬規則,而是一個經驗法則。讓標題保持在 50 字以下能夠確保標題的可讀性,並且強迫作者思考如何用更簡潔的方式表達發生什麼事情。

小提醒:如果你很難總結出標題,這代表你可能在一個 commit 裏面做了太多的改變。請儘量讓 commits 原子化 (atomic commits)。

 

3. 標題開頭要大寫

超簡單的規則,如同字面上的意思,任何標題的開頭都要大寫。

舉例而言:

  • Accelerate to 88 miles per hour

而不是:

  • accelerate to 88 miles per hour

 

 

4. 標題不以句點結尾

結尾的標點符號在標題列是多餘的。此外,當你要遵守 50 字或以下的規則時,字元空間是很寶貴的。

舉例而言:

  • Open the pod bay doors

而非:

  • Open the pod bay doors.

 

5. 以祈使句撰寫標題

已命令的口氣來撰寫你的標題,舉例而言:

  • 清潔你的房間 (Clean your room)
  • 把門關起來 (Close the door)
  • 把垃圾拿走 (Take out the trash)
  • 我們的7條規則也是祈使句 (“Wrap the body at 72 characters”, etc.)。

祈使句看起來有些粗魯;因此我們很少用它。但是對於 Git commit 標題來說卻很適合。其中一個理由是因為 Git 本身就是依照你的命令來完成一個動作。

舉例而言,git merge 預設的 message 是:

NewImage

當使用 git revert:

NewImage

或是在 GitHub PR 按下 “Merge” 按鈕的時候:

NewImage

所以如果你以祈使句撰寫你的 commit messages,你就是在遵循 Git 本身內建的慣例。

舉例而言:

  • Refactor subsystem X for readability
  • Update getting started documentation
  • Remove deprecated methods
  • Release version 1.0.0

 

在一開始這可能會看起來很奇怪。我們比較常使用指示性語句,用來描述事實。這就是為什麼常常看到 commit messages 長這個樣子:

  • Fixed bug with Y
  • Changing behavior of X

而有些 commit messages 會以描述的方式撰寫內容:

  • More fixes for broken stuff
  • Sweet new API methods

為了減少各位的疑惑,這裡有個簡單的規則可以套用,讓事情每次都是正確的。

一個正確的 Git commit 標題應該要能夠讓完成下面的句子,使之完整:

If applied, this commit will 你的標題

記得:”使用祈使句” 規則只在標題是重要的。你可以在撰寫內文時放寬這條規則。

 

6. 內文每行最多 72 字

Git 不會自動 wrap 任何文字。當你在撰寫 commit message 內文的時候,你需要注意左邊的 margin,並且手動的 wrap 起文字。

建議的 72 字可以保留空間讓 Git 自動縮進,使得結果還是在 80 字以下。

 

7. 用內文解釋 what 以及 why vs. how

Bitcoin Core 的這個 commit 給了一個很棒的範例,解釋了什麼改變以及為什麼:

NewImage

自己來看看完整的 diff,你就能想像這個 commit message 的作者花了時間寫下其脈絡,可以讓未來的 committers 省下多少時間。如果他沒有這麼做,這件事情可能就會被埋末再裏面。

在大多數的情況下,你可以省略掉描述這些變更的細節。程式碼本身就已經能自我說明了 (如果程式碼太複雜,必須要有說明的話,這時候就是程式碼本身的註解啦)。你只需要專注在解釋做出這樣改變的原因 ─ 事情在改變前為什麼可行 (以及他的錯誤),他們目前運作的狀況,以及為什麼你決定要以這個方法解決問題。

那個未來會感謝你的維護者,說不定就是你自己!

 

 

Advertisements