如何寫好 commit message

序

現(xiàn)如今，我們的工作基本上離不開版本控制工具了。我們每天都在 commit 代碼編寫 commit message， 但是你知道如何寫出有意義的 commit message 嗎。如果你還在寫 update code 、fix bug 這樣的信息，那么你很有必要看看本文了。

如果你還不會使用Git，推薦閱讀?一篇文章，教你學(xué)會Git

1?? ?為什么 Commit Message 很重要 ?? ?

• 每一個commit可以在你的代碼庫里創(chuàng)建一個個明確的更改節(jié)點(diǎn)。
• 你可以更好地了解代碼中的內(nèi)容是如何被破壞的。
• 可以讓人們看到以前發(fā)生過什么，擁有版本歷史對于理解代碼很重要。
• 用來證明你的工作，如果你不這樣做，那么你注定要在會議上、ticket、報(bào)告中一次又一次地重復(fù)解釋你所做的事情。
• Commit message 在 Code Review 中是十分有意義。

commit message 應(yīng)該清晰明了，應(yīng)該明確告訴你的伙伴，你做了什么，為什么這么做。即使他們沒有看到 代碼，也能理解你所做的事。完全掌握這一點(diǎn)的最佳方法是查看您的項(xiàng)目日志，最好是看看其他人的 Commit。看看你能不能理解他們所做的 commit。

2?? ?良好的 Commit Message 的重要性 ??

一段時(shí)間后，你已經(jīng)對你之前寫代碼一臉懵逼了。當(dāng)項(xiàng)目出現(xiàn) Bug 時(shí)，commit 歷史可以幫助我們快速找出問題究竟出在哪里。這時(shí)你一定希望擁有良好的 Commit message，為您提供有關(guān)更改內(nèi)容和原因的有用信息。

但是，如果此時(shí)滿屏的 update code , fix bug ... 你又該從何下手呢？一定是想把寫這些信息的人打一頓。

當(dāng)你在六個月后回顧你自己的提交歷史時(shí)，試圖想起六個月前你寫那個 commit 時(shí)的想法：

通常來說冗長絕不是一件壞事。事實(shí)上，我們鼓勵程序員在提交中添加冗長的細(xì)節(jié)，但僅限于描述中。摘要可以幫助您和其他程序員瀏覽數(shù)千次提交，因此它必須既簡潔又富有洞察力。

糟糕的提交信息的例子??

是時(shí)候?qū)ι蠄D的垃圾 commit message 說不了?????♀?！

創(chuàng)建一個好的提交信息一點(diǎn)也不難，我們只需要付出一點(diǎn)點(diǎn)努力然后加以實(shí)踐。許多開發(fā)人員往往有編寫糟糕 commit message 的壞習(xí)慣。從今天起，我們應(yīng)該意識到良好 commit message 的重要性。

3?? ?10 個 Commit 規(guī)則 ??

我想花點(diǎn)時(shí)間詳細(xì)說明什么是格式良好的提交消息。你只需要遵循以下 10 條規(guī)則，這將使你的提交信息更清晰，看起來也很舒服，就像下面這樣：

每次提交，Commit message 都包括三個部分：Header，Body 和 Footer。

// 空一行

// 空一行

1. 提交消息由 Header (主題)、Body（詳細(xì)描述） 和 Footer 組成，Body 和 Footer 都是可選的。

2. 將 Header 行 限制為 50 個字符。

• 主題是最能總結(jié)提交中所做更改的一行。
• 總結(jié)提交的行為在任何版本控制系統(tǒng)中都是一種固有的好習(xí)慣。它可以幫助其他人（或后來的您）更快地找到相關(guān)的提交。

3. 將主題行的第一個字母大寫。

4. 不要在主題行的末尾加上句點(diǎn) (.)。

5. 在 Header 和 Body 以及 Footer 之間放置一個空行。

• 將 Header 與 Body 分開的空行很重要（除非您完全省略正文）Footer 也應(yīng)通過空行與正文分開。

6. Body 的行寬不要超過 72 個字符處。

• Body 用于提供有關(guān) commmit 中所做更改的更多詳細(xì)信息。

7. 用項(xiàng)目任務(wù)號寫commit 的 Body（可選）。

• 以項(xiàng)目任務(wù)號編寫時(shí)，提交主體看起來很干凈。

8. 使用祈使語氣

示例：Add 而不是 Added， Fix 而不是 Fixed, Fixes → 主題行使用現(xiàn)在時(shí)命令式，正文使用現(xiàn)在時(shí)態(tài)

9. 描述"什么"和"為什么"，但不描述"如何"。

• 可以提及更改了哪個組件。
• 只關(guān)注目的，而不是實(shí)現(xiàn)。
• 大多數(shù)現(xiàn)代錯誤跟蹤和項(xiàng)目管理系統(tǒng)都提供了與源代碼控制存儲庫的集成，但即使它們沒有集成，你仍然可以在提交消息放上 task/ticket 編號。

10. 在 Footer 中 包含 ticket 號或者 issue no.（如果有的話）。

• Footer 位于 Body 正下方，是引用與提交更改相關(guān)的問題的地方。如在 GitHub 中的 issue no.，JIRA 中的 ticket 號。

除了上面介紹這10個基本commit message 規(guī)則。很多開源項(xiàng)目會在CONTRIBUTING 中說明它們采用的commit message格式，大同小異。

Angular團(tuán)隊(duì)推出的conventional-changelog 最為有名，使用最廣泛。

其格式如下，規(guī)定了type, scope 等。

(): 
// 空一行

// 空一行

筆者幾年前寫過另一篇Git使用文章中有具體介紹，推薦閱讀：更優(yōu)雅的使用 Git

4?? ?什么是 50-72 Commit 規(guī)則？??

git log 不會處理換行，因此如果行太長則很難閱讀。如果提交的描述一行的長度不限于 72 個字符 那么提交信息將跨越命令行的整個寬度，使 commit message 難以閱讀。

以下是當(dāng)您不限制提交正文長度時(shí)，提交消息在 git 中的樣子。

以 72 個字符換行文本可防止文本跨越命令行窗口的整個寬度，提高 commit message 的可讀性。

注意：如果 commit message 的 Body 超過 72 個字符，Github 會自動將他換行 ??

50/72 規(guī)則是一套標(biāo)準(zhǔn)，在行業(yè)中得到了很好的認(rèn)可，是用于標(biāo)準(zhǔn)化提交消息的格式。

50 是 commit message 的 Header 的最大字符數(shù)。Body 應(yīng)該以 72 個字符換行。這兩個數(shù)字不是隨便拍腦袋說出來的任意數(shù)字。

對 Linux kernel 中 commit message 的分析表明，50 個字符是提交標(biāo)題最常見的長度。

數(shù)字 72 來自這樣一個事實(shí)，即 80 個字符是被廣泛接受的一行可讀字符長度的行業(yè)標(biāo)準(zhǔn)，git 會自動在提交消息正文的左側(cè)添加 4 個字符的填充，并且為了保持所有內(nèi)容居中，在右側(cè)也會填充 4 個字符。

5???一些有用的 Commit 工具 ??

前面介紹了一些 commit message 規(guī)則，接下來介紹幾個工具幫我們更好的將這些在項(xiàng)目中實(shí)施落地。

1. Committizen

https://github.com/commitizen/cz-cli

是一個撰寫合格 Commit message 的工具。當(dāng)您使用 Commitizen 提交時(shí)，會有個交互式命令行提示你輸入 commit message 所有必需的提交字段。

首先全局安裝 commitizen

npm?install?commitizen?-g

然后，在項(xiàng)目目錄里，運(yùn)行下面的命令進(jìn)行初始化，使其支持 Angular 的 Commit message 格式。

commitizen?init?cz-conventional-changelog?--save-dev?--save-exact

現(xiàn)在，你就可以是用 git cz 來替代 git commit 命令了。

2. CommitLint

https://commitlint.js.org/

commitlint 用于幫助您的團(tuán)隊(duì)遵守提交約定

安裝

npm?install?-g?@commitlint/cli?@commitlint/config-conventional

在項(xiàng)目里配置

echo?"module.exports?=?{extends:?['@commitlint/config-conventional']}"?>?commitlint.config.js

通常，我們將他與 Git hooks 結(jié)合起來使用，實(shí)現(xiàn)在 commit 時(shí)自動檢查 message 是否合法。

husky 是一個十分易用的處理 git hooks 的 npm 包。

https://github.com/typicode/husky

我們只需要進(jìn)行如下配置就可以開始使用了：

#?安裝?Husky?v6
npm?install?husky?--save-dev

#?激活?hooks
npx?husky?install

#?添加?hook
npx?husky?add?.husky/commit-msg?'npx?--no?--?commitlint?--edit?$1'

現(xiàn)在可以輸入一個不合法的 message 來進(jìn)行測試

git?commit?-m?"foo:?this?will?fail"
husky?>?commit-msg?(node?v10.1.0)
No?staged?files?match?any?of?provided?globs.
????input:?foo:?this?will?fail
????type?must?be?one?of?[build,?chore,?ci,?docs,?feat,?fix,?perf,?refactor,?revert,?style,?test]?[type-enum]

????found?1?problems,?0?warnings
????Get?help:?https://github.com/conventional-changelog/commitlint/#what-is-commitlint

husky?>?commit-msg?hook?failed?(add?--no-verify?to?bypass)

commitlint 也提供了類似于 commitizen 交互式的命令行工具：@commitlint/prompt-cli。有興趣的同學(xué)也可以自行試試。同時(shí)，也可以將 commitlint 與 CI 工具結(jié)合使用。

3. gitmoji

https://gitmoji.dev/

最后我們來介紹一個有意思的項(xiàng)目。在 commit message 中使用 emoji

下表是常用 emoji 所代表的含義：

更多emoji的使用，快去它的官網(wǎng)看看吧！

往期精彩回顧：

關(guān)注公眾號回復(fù)【資源】可免費(fèi)領(lǐng)取學(xué)習(xí)資料！

左手代碼右手磚，拋磚引玉

記得點(diǎn)贊，分享，在看加關(guān)注喲