git commit 規範指南

前言

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

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

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

Commit message 的作用

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

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

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

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

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

可以直接從 commit 生成 Change log。

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

其他優點

可讀性好，清晰，不必深入看代碼即可瞭解當前 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 部分只有一行，包括三個字段：type（必需）、scope（可選）和subject（必需）。

type

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

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

如果 type 爲feat和fix，則該 commit 將肯定出現在 Change log 之中。其他情況（docs、chore、style、refactor、test）由你決定，要不要放入 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 部分以 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 <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。

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

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://segmentfault.com/a/1190000009048911

前言