我們都曾在某個時刻經歷過有關 git commit 訊息的混亂。
我也不例外。我的部落格的提交訊息如下所示：
fixxxx stuff
post
post
post
post
posts
mmm
posts
front maddy
Add chris oliver
add syntax
article
add git patch article
fix video
video
arty art art
Fix links
oops
因為我部落格的 git 歷史記錄只有我自己看過，所以沒關係。我已經接受了我永遠無法在我的部落格中充分利用 git 的事實，而且我完全同意這一點。
不幸的是，有些人對待有多個貢獻者的真實專案就像我對待我的部落格一樣。我發現這種做法是無知而不是懶惰的結果。因此，我將分享一些關於如何在實際專案中使用提交訊息的技巧。
為什麼要關心？
😤我不在乎，跳到模板！ 🚀
Git 是一個強大的工具，即使您只使用它來保存程式碼更改歷史記錄並且不利用其最強大的功能。
然而，你會發現你挖掘得越深，git 就會變得越強大。您還會發現 git 的許多最有用的功能都是在提交訊息有用的假設下運作的。
想想你上次使用git blame是什麼時候。如果您發現一條提交訊息，上面fixed a bad bug ，這會有幫助嗎？可能不是，您可能試圖找到有關您正在處理的程式碼的更多上下文；你需要解釋什麼以及為什麼。
Git 提交訊息必須包含每次更改背後的內容和原因，以便明天勇敢的 git 探索者能夠進入提交作者的頭腦。如果提交訊息不包含該訊息，為什麼還要寫一個？提交訊息只有在對將來某個時候試圖理解更改的人有用時才有用。
為了建立一個良好的提交訊息的模板，我將把提交訊息分成幾個部分。
首先，主題行
在提交訊息中，第一行（有時稱為主題行）應與正文隔離。理想情況下，這一行總結了提交中所做的更改。
當我寫主題行時，我嘗試完成這句話，“這次提交將......”
例如，我可能會編寫一個主題行，內容類似於Remove unused, commented code 。這可以很好地結束我的句子：“此提交將刪除未使用的帶註釋的程式碼。”
在設定主題行格式時，需要記住一兩個規則。
首先，主題行中的第一個字元應大寫；這只是一個常見的約定。根據我的經驗，它還使閱讀一長串的單行提交清單變得更加容易。
其次，您的提交訊息不應超過五十個字元。這是因為 GitHub 等工具會將該行截斷為 50 個字元。因此，為了讓其他人能夠有效地瀏覽和理解你的主題行，你應該嘗試用五十個字符來總結整個變化。
我的提交訊息範本的第一行如下所示：
Summarize the change in less than 50 characters
接下來，第一個正文“段落”
在某些提交中，主題行足以傳達整個想法。例如，如果您的提交將Add a comma to the README ，您可能不需要自己解釋。
然而，在大多數提交中，您的更改可能會受益於一些額外的上下文。我們不希望未來的開發人員在嘗試理解更改背後的原因時錯過上下文。
這就是訊息正文發揮作用的地方。我將正文分為“段落”，這些“段落”只是鬆散定義的由空格分隔的文字字串。它們可以是要點、句子或其他東西；重要的是它們從冷開始就易於閱讀和理解。
過去，我通常使用提交訊息正文的第一段來解釋我所做的事情。這些天，我已經不再關注「什麼」 ，而是開始記錄「為什麼」 。
Ben Orenstein 最近改變了我對提交訊息格式的看法：
{% 推特 1175100703829909505 %}
因此，在這種情況下，我們想要引導我們做出改變的原因。
這是一個例子：
Refactor the coupon UI
Because:
- The old UI code is fairly slow
- There were a few unused dependencies
- The old UI has aged poorly
這些「段落」的偉大之處在於只有一個格式規則：72 個字元換行。這更多的是一種遺留傳統，而不是任何實質的東西。然而，主要原因是這允許 git 縮進一些空間（假設最大字元限制為 80）。我建議遵循這條規則，儘管它並不總是嚴格必要的。
這是到目前為止的提交訊息範本：
Summarize the change in less than 50 characters
Because:
- Explain the reasons you made this change
- Make a new bullet for each reason
- Each line should be under 72 characters
現在是第二正文“段落”
既然我們已經總結了更改並分享了進行更改的原因，那麼以較長的形式準確地解釋我們所做的事情可能是謹慎的做法。
我用第二個「段落」來更詳細地解釋我在更改中所做的事情，例如：
Refactor the coupon UI
Because:
- The old UI code is fairly slow
- There were a few unused dependencies
- The old UI has aged poorly
I thought it was necessary to remove some of the old coupon UI code.
Unfortunately, it has aged pretty poorly, and I think this refactor makes
the code much easier to support in the long-run. Primarily, this commit
improves the performance of the coupon component. It also removes some
unused dependencies.
提交正文的這一部分應該比 50 個字元的摘要更深入地解釋所做的事情。格式由您決定（只要您以 72 個字元換行即可）。
這是更新後的模板：
Summarize the change in less than 50 characters
Because:
- Explain the reasons you made this change
- Make a new bullet for each reason
- Each line should be under 72 characters
Explain exactly what was done in this commit with more depth than the
50 character subject line. Remember to wrap at 72 characters!
其他部分：附加註釋和合著者
此時，我們正在編寫有效且連貫的提交訊息。然而，有時提交訊息需要一些額外的註釋。這可以在最後一節中完成。
例如：
Refactor the coupon UI
Because:
- The old UI code is fairly slow
- There were a few unused dependencies
- The old UI has aged poorly
I thought it was necessary to remove some of the old coupon UI code.
Unfortunately, it has aged pretty poorly, and I think this refactor makes
the code much easier to support in the long-run. Primarily, this commit
improves the performance of the coupon component. It also removes some
unused dependencies.
These changes should resolve issue #1337.
This commit removed the left-pad dependency, so please stop using it!
Co-authored-by: nspinazz89 <[email protected]>
在這個例子中我能夠：
參考相關問題
加入一行以警告我刪除了依賴項
包含與我一起參與該提交的人員的引用
此時，任何查看此提交訊息的人都會知道：
做了什麼一目了然
為什麼需要改變
有關已完成操作的詳細訊息
有關變更的任何有用的詳細訊息
這使得我們的提交訊息對我們未來的自己和任何其他需要理解我們程式碼的開發人員來說更加有用。
即使您不同意我編寫提交訊息的方法，也很難否認我們必須編寫提交訊息，以便其他開發人員在閱讀我們的程式碼時能夠進入我們的視野。
我認為大多數人都同意“好”程式碼的標誌是可維護性，您可以透過編寫有助於其他人理解甚至將來更改您的程式碼的提交訊息來增強程式碼的可維護性。
最終模板
Summarize the change in less than 50 characters
Because:
- Explain the reasons you made this change
- Make a new bullet for each reason
- Each line should be under 72 characters
Explain exactly what was done in this commit with more depth than the
50 character subject line. Remember to wrap at 72 characters!
Include any additional notes, relevant links, or co-authors.
還有更多...
這些天我寫了很多文章，我經營一個播客，並且我已經開始發送一份關於我聽到的所有精彩故事的時事通訊摘要。
您還可以在Twitter上關注我，我在那裡製作一些愚蠢的表情包並談論如何成為開發人員。
原文出處：https://dev.to/jacobherrington/how-to-write-useful-commit-messages-my-commit-message-template-20n9
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式
