我們都看到過的

你在一個項目中使用 Git 作為版本控制。

當你做完了一次修改之后，你想要盡快更新你的分支。

所以你打開了終端，輸入了下面這些命令，完成了一次遠端分支的更新。

git add .
git commit -m "added new feature"
git push

然后你做了一些自測，發現了一個新鮮的 bug。問題不大，你很輕松的就解決掉了這個 bug，現在你需要把新的代碼再次提交到遠程分支，于是你很熟練的使用起 Git 命令。

git add .
git commit -m "fix bug"
git push

你幾乎每天都在重復做著這樣的事情，當你打開 Git log 時，你會發現它長成了這個樣子。

到目前為止，一切看上去對你來說都還不錯。畢竟你很熟悉你的代碼倉庫，即使不需要提交信息的提醒，你也知道每次修改都是在進行了哪些操作。

存在的問題

過了幾個月，其他的開發者瀏覽了你過去的修改，他們想要嘗試更深入的理解關于你所做的修改的一些細節問題，但是你的提交信息并不具備描述性，他們也就無法從中獲取任何有用的信息。

無奈之下，他們只能挨個查看每次提交的不同，然而即使這么做了，他們也還是不能很明確的知道你在開發過程中一些選擇的理由和你的一些思考。

由于軟件開發是一個協作的過程中，所以人們總是會使用 git blame 操作來查看是誰對代碼做了修改，并且會問你一些關于代碼的問題。但是距離你寫這段代碼已經過去很長時間了，你的印象也比較模糊。當你查看你的提交時，你發現自己很難說出當時為什么要這么寫，以及其中的一些邏輯細節。

你給同事發送了一個悲傷的表情，并且告訴他們，你沒有辦法給他們提供更多的信息。

書寫優秀的提交信息

希望通過上面的故事，你已經知道了為什么要編寫良好的、信息豐富的 Git 提交信息：

在軟件工程這樣需要協作的領域中，它可以幫助我們快速理解上下文。理想情況下，Git 提交信息需要由三部分組成：主題、正文和結語。

主題

主題需要是一句話來概括你提交內容所涉及的修改。它需要是祈使時態，以大寫字母開頭，結尾沒有句號，并且最好小于50個字。

一個好的主題格式應該是像“This commit will …”這樣的。好的提交信息也應該是一個比較完整的句子。“add new neural network model to back-end”。

而不好的提交信息就不是一個完整描述的句子，比如最常見的“fix bug”。

正文

正文需要包含你要傳達的信息，讓其他人在其中能夠了解更多關于這次修改的細節。對于一些比較修改的修改，比如改動了一個變量類型，你可能不需要寫正文，主題就足夠描述這次修改的內容了。

在正文中，你應該更詳細的描述這次修改中的一些細節問題，并且解釋你所做的事情的前因后果。

你可以解釋為什么要做出這個修改，為什么用這種特殊的方式來實現，或者其他你覺得能夠幫助其他人理解你的修改過程的信息。

注意不要重復描述代碼中顯而易見的邏輯，正文也不是讓你一行一行的解釋代碼，大家更加關注的是代碼中不容易看出來的更深層的一些細節問題。我們的最終目標是為這次的修改提供有效的上下文信息，即更改主要的動機和目標。

結束語

最后，結束語應該出現在你的提交信息的最后一行。

你可以在這里提供一些關于此次修改的元數據，比如 JIRA 號，GitHub issue 號，合作者姓名，和附加信息的鏈接。

這有助于將你的修改的相關重要信息鏈接在一起。