編寫git commit資訊的最佳實踐

Gavin發表於2018-12-18
GitMIT

翻譯自：Write good git commit message

寫好Git提交資訊

很長時間以來，我甚至都不知道編寫 git 提交（commit）資訊也有它自己的“最佳實踐”。在我第一次接觸 git 時，提交資訊的那部分內容被描述為類似這樣的話："...and here you can write something short about what`s going on in the commit"。

不好的提交資訊

請看下面的提交資訊。如果你想合併它們，你真的不會知道哪些是新增的內容，哪些是修改的內容，它們做了什麼或者你為什麼需要它們。如果你想在歷史記錄中搜尋某些內容，那麼上述的糟糕情況同樣會遇到。你向下滾動日誌，但它仍是一團糟，並且浪費時間。

cd3e27a contact page
aee9d0d comments
eac95e5 list of online users, some other changes because of server
fae5636 little edit

好的提交資訊

現在再看下這些提交資訊。是不是感覺好多了？反正我是這麼覺得。

43ec6aa Fix error when the URL is not reachable
4fe84ab Add error message if something went wrong
753aa05 Add server fingerprint check
df3a662 Fix shadow box closing problem

如何編寫好的提交資訊

整個 commit 資訊應該有它的格式 – 主題、正文以及可選的由已解決/已關閉的問題組成的結論。

主題

Git 的 commit 幫助頁面對提交資訊的主題有個很不錯的描述：對變更內容進行總結的單行文字（少於50個字元），後跟一個空行。主題應以大寫字母開頭且不以句點 . 結尾。而且重要的是，這必須是一個強制的形式。Chris Beams 為此寫了一個簡單的規則：

Git 提交資訊主題的形式應該總是能夠符合這樣的句式：如果提交被應用，那麼這個提交將“你寫的主題”。比如：

【譯註】這裡可以把“你寫的主題”理解成一個動詞、一個動作。

  • 如果被應用，那麼這個提交將刪除(Delete)不需要的行。
  • 如果被應用，那麼這個提交將新增(Add) grep 選項。
  • 如果被應用，那麼這個提交將修復(Fix)協議缺失時錯誤。

對於不好的提交資訊，就不會符合這個句式：

  • 如果被應用，那麼這個提交將Contact page。
  • 如果被應用，那麼這個提交將list of online users, some other changes because of server。

Git 本身就是使用這種方法。當你要合併某些內容時，Git 會生成一個類似這樣的提交資訊："Merge branch..."，或者回滾時生成 "Revert..."。

正文

在正文裡你可以編寫哪些內容被修改了以及為什麼修改。正文的每一行不應超過72個字元。當然並不是每次提交都需要有正文。

尾行

最後，你可以新增此次 commit 修復的或相關的 issue。它可以是一個連結、數字或者如果你在使用 GitHub，你可以這樣寫：Resolves #N / Closes #N，這裡的 N 表示 issue ID。

示例

這是一個來自我的倉庫的提交資訊示例：

Fix error when protocol is missing

First, it checks if the protocol is set. If not, it changes the url and
add the basic http protocol on the beginning.
Second, it does a "preflight" request and follows all redirects and
returns the last URL. The process then continues with this URL.

Resolves #17

寫在最後

感謝你的閱讀，希望你從中學到了一些新的東西。如果你有其他的關於如何編寫更好的提交訊息的提示，或者如何更好地使用此工具，請發表你的評論。

生成變更日誌

這樣編寫提交資訊的另一個好處就是很容易生成變更日誌。

# show whole commit history
$ git log --oneline --decorate --color

# show history from one tag to another
$ git log 0.0.9..0.0.10 --oneline --decorate --color

# show history form tag to head
git log 0.0.9..HEAD --oneline --decorate --color

這種命令的結果就是你的提交列表。

21629ee Fix getResources bug
aa13384 Update docs
44de44c Add HSTS check

Commitizen

在 GitHub 上有個名叫 Commitizen 的命令列工具，它可以讓提交資訊的編寫變得更容易。當你想提交的時候，你只需鍵入 git cz，它會問你一組問題，然後為你建立正確的提交資訊。

參考

Git commit manpage

Closing issues using keywords on GitHub

How to Write a Git Commit Message post from Chris Beams

Angular Commit Message Format

相關文章