git commit規範

1. git commit說明

我們都知道,Git 每次提交代碼,都要寫 Commit message(提交說明),否則就不允許提交,這其實就是規範,但輸入的說明我們可以隨便寫,之前我也會隨便寫,後來看到同事都很規範的寫,就學習了一下。

$ git commit -m "hello world"

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

如果一行不夠,可以只執行git commit,就會跳出文本編輯器,讓你寫多行。

$ git commit

一般來說,commit message 應該清晰明瞭,說明本次提交的目的。而且多人協作的時候,有問題也方便查看提交日誌

img

列一張我們項目的提交,我是剛開始用有些也不是很規範,當然在gitlab上查看圖形化還是很方便的,對有些習慣用命令行的查看,這種規範就會很有作用了。

這裏寫圖片描述

這好像是Angular 規範,這是目前使用最廣的寫法,比較合理和系統化,並且有配套的工具。

2. Commit message 作用

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

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

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

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

img

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

比如,下面的命令僅僅顯示本次發佈新增加的功能。

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

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

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

img

3. Commit message 的格式規範

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

<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>

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

不管是哪一個部分,任何一行都不要有太多字符。這是爲了避免自動換行影響美觀。

3.1 Message Subject(Header)

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

(1)type

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

  • feat:新功能(這裏寫圖片描述)
  • fix:修補bug( 這裏寫圖片描述)
  • docs:修改文檔( 這裏寫圖片描述
  • style: 格式化代碼結構(不影響代碼運行的變動 這裏寫圖片描述 )
  • refactor:重構(即不是新增功能,也不是修改bug的代碼變動,比如重命名變量 這裏寫圖片描述
  • chore:構建過程或輔助工具的變動(不會影響代碼運行)

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

除此之外,還提供了一種表情符號的方式,在標識前再加一個:就可以顯示了,我喜歡這種方式,有意思還明瞭。

這裏寫圖片描述
這裏寫圖片描述

(2)scope

scope用於定義type影響的範圍,比如數據層、控制層、視圖層等等,視項目不同而不同。

(3)subject

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

  • 以動詞開頭,使用第一人稱現在時,比如change,而不是changedchanges
  • 第一個字母小寫
  • 結尾不加句號(.

3.2 Body

Body 部分是對本次 commit 的詳細描述,可以分成多行,每行儘量不超過72個字符。下面是一個範例。

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

Footer 部分只用於兩種情況。

(1)不兼容變動

如果當前代碼與上一個版本不兼容,則 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.

(2)關閉 Issue

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

Closes #234

也可以一次關閉多個 issue 。

Closes #123, #245, #992

3.4 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小標題下面。

4. Commitizen

Commitizen是一個撰寫合格 Commit message 的工具。

安裝命令如下。

$ npm install -g commitizen

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

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

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

img

5. 生成 Change log

如果你的所有 Commit 都符合 Angular 格式,那麼發佈新版本時, Change log 就可以用腳本自動生成(例1例2例3)。

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

  • 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

上面命令不會覆蓋以前的 Change log,只會在CHANGELOG.md的頭部加上自從上次發佈以來的變動。

如果你想生成所有發佈的 Change log,要改爲運行下面的命令。

$ conventional-changelog -p angular -i CHANGELOG.md -w -r 0

爲了方便使用,可以將其寫入package.jsonscripts字段。

{
"scripts": {
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -w -r 0"
}
}

以後,直接運行下面的命令即可。

$ npm run changelog

參考:

https://github.com/slashsBin/styleguide-git-commit-message

http://www.ruanyifeng.com/blog/2016/01/commit_message_change_log.html

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章