git commit 規范指南

前言

Git 每次提交代碼,都要寫 Commit message(提交說明),否則就不允許提交。但是,一般來說,commit message 應該清晰明了,說明本次提交的目的。

不過話說回來,作為最具個人創造力和最會利用工具的物種——程序猿,最好是能有規范和工具的約束。否者的話,你可能看到以下的commit message

1.png

目前,社區有多種 Commit message 的寫法規范。本文介紹Angular 規范是目前使用最廣的寫法,比較合理和系統化,并且有配套的工具。前前端框架Angular.js采用的就是該規范。如下圖:

2.png

Commit message 的作用

提供更多的歷史信息,方便快速瀏覽。

比如,下面的命令顯示上次發布后的變動,每個commit占據一行。你只看行首,就知道某次 commit 的目的。

$ git log <last tag> HEAD --pretty=format:%s
3.png

可以過濾某些commit(比如文檔改動),便于快速查找信息

$ git log <last release> HEAD --grep feature

可以直接從commit生成Change log。

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

4.png

其他優點

  • 可讀性好,清晰,不必深入看代碼即可了解當前commit的作用。

  • 為 Code Reviewing做準備

  • 方便跟蹤工程歷史

  • 讓其他的開發者在運行 git blame 的時候想跪謝

  • 提高項目的整體質量,提高個人工程素質

Commit message 的格式

每次提交,Commit message 都包括三個部分:header,body 和 footer。

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

其中,header 是必需的,body 和 footer 可以省略。
不管是哪一個部分,任何一行都不得超過72個字符(或100個字符)。這是為了避免自動換行影響美觀。

Header

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

type

用于說明 commit 的類別,只允許使用下面7個標識。

  • feat:新功能(feature)

  • fix:修補bug

  • docs:文檔(documentation)

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

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

  • test:增加測試

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

如果type為featfix,則該 commit 將肯定出現在 Change log 之中。其他情況(docschorestylerefactortest)由你決定,要不要放入 Change log,建議是不要。

scope

scope用于說明 commit 影響的范圍,比如數據層、控制層、視圖層等等,視項目不同而不同。

例如在Angular,可以是$location, $browser, $compile, $rootScope, ngHref, ngClick, ngView等。

如果你的修改影響了不止一個scope,你可以使用*代替。

subject

subject是 commit 目的的簡短描述,不超過50個字符。

其他注意事項:

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

  • 第一個字母小寫

  • 結尾不加句號(.)

Body

Body 部分是對本次 commit 的詳細描述,可以分成多行。下面是一個范例。

More detailed explanatory text, if necessary.  Wrap it to 
about 72 characters or so. 

Further paragraphs come after blank lines.

- Bullet points are okay, too
- Use a hanging indent

有兩個注意點:

  • 使用第一人稱現在時,比如使用change而不是changed或changes。

  • 永遠別忘了第2行是空行

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

Footer

Footer 部分只用于以下兩種情況:

不兼容變動

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

BREAKING CHANGE: isolate scope bindings definition has changed.

    To migrate the code follow the example below:

    Before:

    scope: {
      myAttr: 'attribute',
    }

    After:

    scope: {
      myAttr: '@',
    }

    The removed `inject` wasn't generaly useful for directives so there should be no code using it.

關閉 Issue

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

Closes #234

Revert

還有一種特殊情況,如果當前 commit 用于撤銷以前的 commit,則必須以revert:開頭,后面跟著被撤銷 Commit 的 Header。

revert: feat(pencil): add 'graphiteWidth' option

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

Body部分的格式是固定的,必須寫成This reverts commit &lt;hash>.,其中的hash是被撤銷 commit 的 SHA 標識符。

如果當前 commit 與被撤銷的 commit,在同一個發布(release)里面,那么它們都不會出現在 Change log 里面。如果兩者在不同的發布,那么當前 commit,會出現在 Change log 的Reverts小標題下面。

Commitizen

可以使用典型的git工作流程或通過使用CLI向導Commitizen來添加提交消息格式。

安裝

npm install -g commitizen

然后,在項目目錄里,運行下面的命令,使其支持 Angular 的 Commit message 格式。

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

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

5.png

validate-commit-msg

validate-commit-msg 用于檢查項目的 Commit message 是否符合Angular規范。

該包提供了使用githooks來校驗commit message的一些二進制文件。在這里,我推薦使用husky,只需要添加"commitmsg": "validate-commit-msg"到你的package.json中的nam scripts即可.

當然,你還可以通過定義配置文件.vcmrc來自定義校驗格式。詳細使用請見文檔 validate-commit-msg

生成 Change log

如果你的所有 Commit 都符合 Angular 格式,那么發布新版本時, Change log 就可以用腳本自動生成。生成的文檔包括以下三個部分:

  • New features

  • Bug fixes

  • Breaking changes.

每個部分都會羅列相關的 commit ,并且有指向這些 commit 的鏈接。當然,生成的文檔允許手動修改,所以發布前,你還可以添加其他內容。

conventional-changelog 就是生成 Change log 的工具,運行下面的命令即可。

$ npm install -g conventional-changelog
$ cd my-project
$ conventional-changelog -p angular -i CHANGELOG.md -w

參考文章

Commit message 和 Change log 編寫指南
Angular.js Git Commit Guidelines


原文:https://segmentfault.com/a/1190000009048911

?著作權歸作者所有,轉載或內容合作請聯系作者
平臺聲明:文章內容(如有圖片或視頻亦包括在內)由作者上傳并發布,文章內容僅代表作者本人觀點,簡書系信息發布平臺,僅提供信息存儲服務。
  • 序言:七十年代末,一起剝皮案震驚了整個濱河市,隨后出現的幾起案子,更是在濱河造成了極大的恐慌,老刑警劉巖,帶你破解...
    沈念sama閱讀 228,156評論 6 531
  • 序言:濱河連續發生了三起死亡事件,死亡現場離奇詭異,居然都是意外死亡,警方通過查閱死者的電腦和手機,發現死者居然都...
    沈念sama閱讀 98,401評論 3 415
  • 文/潘曉璐 我一進店門,熙熙樓的掌柜王于貴愁眉苦臉地迎上來,“玉大人,你說我怎么就攤上這事。” “怎么了?”我有些...
    開封第一講書人閱讀 176,069評論 0 373
  • 文/不壞的土叔 我叫張陵,是天一觀的道長。 經常有香客問我,道長,這世上最難降的妖魔是什么? 我笑而不...
    開封第一講書人閱讀 62,873評論 1 309
  • 正文 為了忘掉前任,我火速辦了婚禮,結果婚禮上,老公的妹妹穿的比我還像新娘。我一直安慰自己,他們只是感情好,可當我...
    茶點故事閱讀 71,635評論 6 408
  • 文/花漫 我一把揭開白布。 她就那樣靜靜地躺著,像睡著了一般。 火紅的嫁衣襯著肌膚如雪。 梳的紋絲不亂的頭發上,一...
    開封第一講書人閱讀 55,128評論 1 323
  • 那天,我揣著相機與錄音,去河邊找鬼。 笑死,一個胖子當著我的面吹牛,可吹牛的內容都是我干的。 我是一名探鬼主播,決...
    沈念sama閱讀 43,203評論 3 441
  • 文/蒼蘭香墨 我猛地睜開眼,長吁一口氣:“原來是場噩夢啊……” “哼!你這毒婦竟也來了?” 一聲冷哼從身側響起,我...
    開封第一講書人閱讀 42,365評論 0 288
  • 序言:老撾萬榮一對情侶失蹤,失蹤者是張志新(化名)和其女友劉穎,沒想到半個月后,有當地人在樹林里發現了一具尸體,經...
    沈念sama閱讀 48,881評論 1 334
  • 正文 獨居荒郊野嶺守林人離奇死亡,尸身上長有42處帶血的膿包…… 初始之章·張勛 以下內容為張勛視角 年9月15日...
    茶點故事閱讀 40,733評論 3 354
  • 正文 我和宋清朗相戀三年,在試婚紗的時候發現自己被綠了。 大學時的朋友給我發了我未婚夫和他白月光在一起吃飯的照片。...
    茶點故事閱讀 42,935評論 1 369
  • 序言:一個原本活蹦亂跳的男人離奇死亡,死狀恐怖,靈堂內的尸體忽然破棺而出,到底是詐尸還是另有隱情,我是刑警寧澤,帶...
    沈念sama閱讀 38,475評論 5 358
  • 正文 年R本政府宣布,位于F島的核電站,受9級特大地震影響,放射性物質發生泄漏。R本人自食惡果不足惜,卻給世界環境...
    茶點故事閱讀 44,172評論 3 347
  • 文/蒙蒙 一、第九天 我趴在偏房一處隱蔽的房頂上張望。 院中可真熱鬧,春花似錦、人聲如沸。這莊子的主人今日做“春日...
    開封第一講書人閱讀 34,582評論 0 26
  • 文/蒼蘭香墨 我抬頭看了看天上的太陽。三九已至,卻和暖如春,著一層夾襖步出監牢的瞬間,已是汗流浹背。 一陣腳步聲響...
    開封第一講書人閱讀 35,821評論 1 282
  • 我被黑心中介騙來泰國打工, 沒想到剛下飛機就差點兒被人妖公主榨干…… 1. 我叫王不留,地道東北人。 一個月前我還...
    沈念sama閱讀 51,595評論 3 390
  • 正文 我出身青樓,卻偏偏與公主長得像,于是被迫代替她去往敵國和親。 傳聞我的和親對象是個殘疾皇子,可洞房花燭夜當晚...
    茶點故事閱讀 47,908評論 2 372

推薦閱讀更多精彩內容