git commit 規(guī)范

Git 每次提交代碼，都要寫 Commit message（提交說明），否則就不允許提交。

$ git commit -m "hello world"

上面代碼的-m參數(shù)，就是用來指定 commit mesage 的。

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

$ git commit

基本上，你寫什么都行（這里，這里和這里）。

img

但是，一般來說，commit message 應(yīng)該清晰明了，說明本次提交的目的。

img

目前，社區(qū)有多種 Commit message 的寫法規(guī)范。本文介紹Angular 規(guī)范（見上圖），這是目前使用最廣的寫法，比較合理和系統(tǒng)化，并且有配套的工具。

一、Commit message 的作用

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

（1）提供更多的歷史信息，方便快速瀏覽。

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

$ git log <last tagHEAD --pretty=format:%s
img

（2）可以過濾某些commit（比如文檔改動），便于快速查找信息。

比如，下面的命令僅僅顯示本次發(fā)布新增加的功能。

$ git log <last releaseHEAD --grep feature

（3）可以直接從commit生成Change log。

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

img

二、Commit message 的格式

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

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

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

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

2.1 Header

Header部分只有一行，包括三個字段：type（必需）、scope（可選）和subject（必需）。

（1）type

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

  • feat：新功能（feature）
  • fix：修補bug
  • docs：文檔（documentation）
  • style： 格式（不影響代碼運行的變動）
  • refactor：重構(gòu)（即不是新增功能，也不是修改bug的代碼變動）
  • test：增加測試
  • chore：構(gòu)建過程或輔助工具的變動

如果type為feat和fix，則該 commit 將肯定出現(xiàn)在 Change log 之中。其他情況（docs、chore、style、refactor、test）由你決定，要不要放入 Change log，建議是不要。

（2）scope

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

（3）subject

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

  • 以動詞開頭，使用第一人稱現(xiàn)在時，比如change，而不是changed或changes
  • 第一個字母小寫
  • 結(jié)尾不加句號（.）

2.2 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

有兩個注意點。

（1）使用第一人稱現(xiàn)在時，比如使用change而不是changed或changes。

（2）應(yīng)該說明代碼變動的動機，以及與以前行為的對比。

2.3 Footer

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）關(guān)閉 Issue

如果當前 commit 針對某個issue，那么可以在 Footer 部分關(guān)閉這個 issue 。

Closes #234

也可以一次關(guān)閉多個 issue 。

Closes #123, #245, #992

2.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，在同一個發(fā)布（release）里面，那么它們都不會出現(xiàn)在 Change log 里面。如果兩者在不同的發(fā)布，那么當前 commit，會出現(xiàn)在 Change log 的Reverts小標題下面。

三、Commitizen

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

安裝命令如下。

$ npm install -g commitizen

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

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

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

img

四、validate-commit-msg

validate-commit-msg 用于檢查 Node 項目的 Commit message 是否符合格式。

它的安裝是手動的。首先，拷貝下面這個JS文件，放入你的代碼庫。文件名可以取為validate-commit-msg.js。

接著，把這個腳本加入 Git 的 hook。下面是在package.json里面使用 ghooks，把這個腳本加為commit-msg時運行。

  "config": {
    "ghooks": {
      "commit-msg": "./validate-commit-msg.js"
    }
  }

然后，每次git commit的時候，這個腳本就會自動檢查 Commit message 是否合格。如果不合格，就會報錯。

$ git add -A 
$ git commit -m "edit markdown" 
INVALID COMMIT MSG: does not match "<type>(<scope>): <subject>" ! was: edit markdown

五、生成 Change log

如果你的所有 Commit 都符合 Angular 格式，那么發(fā)布新版本時， Change log 就可以用腳本自動生成（例1，例2，例3）。

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

  • New features
  • Bug fixes
  • Breaking changes.

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

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

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

上面命令不會覆蓋以前的 Change log，只會在CHANGELOG.md的頭部加上自從上次發(fā)布以來的變動。

如果你想生成所有發(fā)布的 Change log，要改為運行下面的命令。

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

為了方便使用，可以將其寫入package.json的scripts字段。

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

以后，直接運行下面的命令即可。

$ npm run changelog

原文地址：
Commit message 和 Change log 編寫指南
http://www.ruanyifeng.com/blog/2016/01/commit_message_change_log.html

?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時請結(jié)合常識與多方信息審慎甄別。
平臺聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點，簡書系信息發(fā)布平臺，僅提供信息存儲服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

  • 前言 Git 每次提交代碼，都要寫 Commit message（提交說明），否則就不允許提交。但是，一般來說，c...
    guanguans閱讀 126,937評論 1贊 63
  • 分支 master分支為主分支（保護分支），不能直接在master上進行修改代碼或提交,通過MR(merge Re...
    小花生_peanut閱讀 7,235評論 0贊 4
  • 采用 Angular 的 commit 規(guī)范。 不寫 commit message 不允許提交代碼，具體的規(guī)范格式...
    前端大飛閱讀 7,417評論 1贊 6
  • git commit規(guī)范 git-commit規(guī)范 在多人協(xié)作項目中，如果代碼風(fēng)格統(tǒng)一、代碼提交信息的說明準確，那...
    前端小丸子閱讀 1,804評論 0贊 2
  • 最近這陣子在看一本非常好看的小說-《覆漢》。 三國題材無疑是眾多寫手云集的熱點區(qū)域，各種寫法，各類視角，可以說已經(jīng)...
    沉默的臨冬城主閱讀 399評論 0贊 0

友情鏈接更多精彩內(nèi)容