天天看點

Git 送出的正确姿勢:Commit message 編寫指南

Git 送出的正确姿勢:Commit message 編寫指南

Git 每次送出代碼,都要寫 Commit message(送出說明),否則就不允許送出。

上面代碼的<code>-m</code>參數,就是用來指定 commit mesage 的。

如果一行不夠,可以隻執行<code>git commit</code>,就會跳出文本編譯器,讓你寫多行。

Git 送出的正确姿勢:Commit message 編寫指南

但是,一般來說,commit message 應該清晰明了,說明本次送出的目的。

Git 送出的正确姿勢:Commit message 編寫指南

格式化的Commit message,有幾個好處。

(1)提供更多的曆史資訊,友善快速浏覽。

比如,下面的指令顯示上次釋出後的變動,每個commit占據一行。你隻看行首,就知道某次 commit 的目的。

Git 送出的正确姿勢:Commit message 編寫指南

(2)可以過濾某些commit(比如文檔改動),便于快速查找資訊。

比如,下面的指令僅僅顯示本次釋出新增加的功能。

(3)可以直接從commit生成Change log。

Change Log 是釋出新版本時,用來說明與上一個版本差異的文檔,詳見後文。

Git 送出的正确姿勢:Commit message 編寫指南

每次送出,Commit message 都包括三個部分:Header,Body 和 Footer。

其中,Header 是必需的,Body 和 Footer 可以省略。

不管是哪一個部分,任何一行都不得超過72個字元(或100個字元)。這是為了避免自動換行影響美觀。

Header部分隻有一行,包括三個字段:<code>type</code>(必需)、<code>scope</code>(可選)和<code>subject</code>(必需)。

(1)type

<code>type</code>用于說明 commit 的類别,隻允許使用下面7個辨別。

feat:新功能(feature)

fix:修補bug

docs:文檔(documentation)

style: 格式(不影響代碼運作的變動)

refactor:重構(即不是新增功能,也不是修改bug的代碼變動)

test:增加測試

chore:建構過程或輔助工具的變動

如果<code>type</code>為<code>feat</code>和<code>fix</code>,則該 commit 将肯定出現在 Change log 之中。其他情況(<code>docs</code>、<code>chore</code>、<code>style</code>、<code>refactor</code>、<code>test</code>)由你決定,要不要放入 Change log,建議是不要。

(2)scope

<code>scope</code>用于說明 commit 影響的範圍,比如資料層、控制層、視圖層等等,視項目不同而不同。

(3)subject

<code>subject</code>是 commit 目的的簡短描述,不超過50個字元。

以動詞開頭,使用第一人稱現在時,比如<code>change</code>,而不是<code>changed</code>或<code>changes</code>

第一個字母小寫

結尾不加句号(<code>.</code>)

Body 部分是對本次 commit 的較長的描述,可以分成多行。下面是一個範例。

有兩個注意點。

(1)使用第一人稱現在時,比如使用<code>change</code>而不是<code>changed</code>或<code>changes</code>。

(2)應該說明代碼變動的動機,以及與以前行為的對比。

Footer 部分隻用于兩種情況。

(1)不相容變動

如果目前代碼與上一個版本不相容,則 Footer 部分以<code>BREAKING CHANGE</code>開頭,後面是對變動的描述、以及變動理由和遷移方法。

(2)關閉 Issue

如果目前 commit 針對某個issue,那麼可以在 Footer 部分關閉這個 issue 。

也可以一次關閉多個 issue 。

還有一種特殊情況,如果目前 commit 用于撤銷以前的 commit,則必須以<code>revert:</code>開頭,後面跟着被撤銷 Commit 的 Header。

Body部分的格式是固定的,必須寫成<code>This reverts commit &amp;lt;hash&gt;.</code>,其中的<code>hash</code>是被撤銷 commit 的 SHA 辨別符。

如果目前 commit 與被撤銷的 commit,在同一個釋出(release)裡面,那麼它們都不會出現在 Change log 裡面。如果兩者在不同的釋出,那麼目前 commit,會出現在 Change log 的<code>Reverts</code>小标題下面。

安裝指令如下。

然後,在項目目錄裡,運作下面的指令,使其支援 Angular 的 Commit message 格式。

以後,凡是用到<code>git commit</code>指令,一律改為使用<code>git cz</code>。這時,就會出現選項,用來生成符合格式的 Commit message。

Git 送出的正确姿勢:Commit message 編寫指南

然後,每次<code>git commit</code>的時候,這個腳本就會自動檢查 Commit message 是否合格。如果不合格,就會報錯。

生成的文檔包括以下三個部分。

New features

Bug fixes

Breaking changes.

每個部分都會羅列相關的 commit ,并且有指向這些 commit 的連結。當然,生成的文檔允許手動修改,是以釋出前,你還可以添加其他内容。

上面指令不會覆寫以前的 Change log,隻會在<code>CHANGELOG.md</code>的頭部加上自從上次釋出以來的變動。

如果你想生成所有釋出的 Change log,要改為運作下面的指令。

為了友善使用,可以将其寫入<code>package.json</code>的<code>scripts</code>字段。

以後,直接運作下面的指令即可。

上一篇: kmp算法

繼續閱讀