讓你的 commit 更有價值

時間 2020-07-28

標籤讓你 commit 價值简体版

原文原文鏈接

一個持續更新的github筆記，連接地址：Front-End-Basics，本文地址：讓你的 commit 更有價值。html

提交規範

AngularJS 在開發者文檔中關於 git commit 的指導說明，提到嚴格的 git commit 格式規範能夠在瀏覽項目歷史的過程當中看到更易讀的信息，而且能用 git commit 的信息直接生成 AngularJS 的 change log 。node

commit messages 格式規範

commit messages 由 header 、body 、footer 組成。webpack

header 又包含 type 、scope 、subject 。header 是必需的，不過其中的 scope 是可選的。git

body 和 footer 能夠省略。github

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

注：爲了能在 github 以及各類 git 工具中看得更清晰，commit messages 的每一行都不要超過 100 個字符。

Header

Type

類型必須是如下幾種之一：web

feat: 新功能
fix: bug 修復
docs: 僅修改文檔
style: 修改格式（空格，格式化，省略分號等），對代碼運行沒有影響
refactor: 重構（既不是修 bug ，也不是加功能）
build: 構建流程、外部依賴變動，好比升級 npm 包、修改 webpack 配置等
perf: 性能優化
test: 測試相關
chore: 對構建過程或輔助工具和庫（如文檔生成）的更改
ci: ci 相關的更改

除此以外，還有一個特殊的類型 revert ，若是當前提交是爲了撤銷以前的某次提交，應該用 revert 開頭，後面加上被撤銷的提交的 header，在 body 中應該註明： This reverts commit <hash>. ，hash 指的就是將要被撤銷的 commit SHA 。express

// 例如

revert: feat(user): add user type

This reverts commit ca16a365467e17915f0273392f4a13331b17617d.

Scope

scope 能夠指定提交更改的影響範圍，這個視項目而定，當修改影響超過單個的 scope 時，能夠指定爲 * 。npm

Sbuject

subject 是指更改的簡潔描述，長度約定在 50 個字符之內，一般遵循如下幾個規範：json

用動詞開頭，第一人稱如今時表述，例如：change 代替 changed 或 changes
第一個字母小寫
結尾不加句號（.）

Body

body 部分是對本地 commit 的詳細描述，能夠分紅多行。api

跟 subject 相似，用動詞開頭，第一人稱如今時表述，例如：change 代替 changed 或 changes。

body 應該說明修改的緣由和更改先後的行爲對比。

Footer

footer 基本用在這兩種狀況：

不兼容的改動（ Breaking Changes ）,一般用 BREAKING CHANGE: 開頭，後面跟一個空格或兩個換行符。剩餘的部分就是用來講明這個變更的信息和遷移方法等。
關閉 Issue, github 關閉 Issue 的例子

// BREAKING CHANGE: 的例子
BREAKING CHANGE: isolate scope bindings definition has changed and
    the inject option for the directive controller injection was removed.

    To migrate the code follow the example below:

    Before:

    scope: {
      myAttr: 'attribute',
      myBind: 'bind',
      myExpression: 'expression',
      myEval: 'evaluate',
      myAccessor: 'accessor'
    }

    After:

    scope: {
      myAttr: '@',
      myBind: '@',
      myExpression: '&',
      // myEval - usually not useful, but in cases where the expression is assignable, you can use '='
      myAccessor: '=' // in directive's template change myAccessor() to myAccessor
    }

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



// Closes Issue 例子
Closes #2314, #3421

完整的例子

例一: feat

feat($browser): onUrlChange event (popstate/hashchange/polling)

Added new event to $browser:
- forward popstate event if available
- forward hashchange event if popstate not available
- do polling when neither popstate nor hashchange available

Breaks $browser.onHashChange, which was removed (use onUrlChange instead)

例二: fix

fix($compile): couple of unit tests for IE9

Older IEs serialize html uppercased, but IE9 does not...
Would be better to expect case insensitive, unfortunately jasmine does
not allow to user regexps for throw expectations.

Closes #392
Breaks foo.bar api, foo.baz should be used instead

例三: style

style($location): add couple of missing semi colons

查看更多例子

規範 commit message 的好處

首行就是簡潔實用的關鍵信息，方便在 git history 中快速瀏覽
具備詳實的 body 和 footer ，能夠清晰的看出某次提交的目的和影響
能夠經過 type 過濾出想要查找的信息，也能夠經過關鍵字快速查找相關提交
能夠直接從 commit 生成 change log

// 列舉幾個經常使用的 log 參數

// 輸出 log 的首行
git log --pretty=oneline

// 只輸出首行的 commit 信息。不包含 hash 和 合併信息等
git log --pretty=format:%s

// 查找有關「更新菜單配置項」的提交
git log --grep="更新菜單配置項"

// 打印出 chenfangxu 的提交
git log --author=chenfangxu

// 紅色的短 hash，黃色的 ref , 綠色的相對時間
git log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr)%Creset'

用工具實現規範提交

上面介紹了規範提交的格式，若是讓各位同窗在 git commit 的時候嚴格按照上面的規範來寫，首先心智是有負擔的，得記住不一樣的類型究竟是用來定義什麼的，subject 怎麼寫，body 怎麼寫，footer 要不要寫。其次，對人的規範大部分都是反人性的，因此極可能在過不了多久，就會有同窗漸漸的不按照規範來寫。靠意志力來控制本身嚴格按照規範來寫是須要額外耗費一些精力的，把精力耗費在這種事情上面實在有些浪費。

用工具實現規範提交的方案，一種是在提交的時候就提示必填字段，另外一種是在提交後校驗字段是否符合規範。這兩種在實際項目中都是頗有必要的。

Commitizen

Zen-like commit messages for internet citizens. 嗯~~一種禪意

Commitizen 是一個幫助撰寫規範 commit message 的工具。他有一個命令行工具 cz-cli，接下來會把使用 Commitizen 分紅幾個階段來介紹。

體驗 git cz

// 全局安裝 Commitizen
npm install -g commitizen

你的倉庫可能還不是對 Commitizen 友好的，此時運行 git cz 的效果跟 git commit 同樣，也就是沒有效果。不過，能夠執行 npx git-cz 來體驗。

若是想直接運行 git cz 實現語義化的提交，能夠根據 streamich/git-cz 文檔中說的全局安裝 git cz。

// 全局安裝 git cz
npm install -g git-cz

除此以外還有一種更推薦的方式，就是讓你的倉庫對 Commitizen 友好。

Commitizen 友好

全局安裝 Commitizen 後，用 cz-conventional-changelog 適配器來初始化你的項目

// 初始化 cz-conventional-changelog 適配器
commitizen init cz-conventional-changelog --save-dev --save-exact

上面的初始化作了三件事：

安裝 cz-conventional-changelog 依賴
把依賴保存到 package.json 的 dependencies 或 devDependencies 中
在根目錄的 package.json 中添加以下所示的 config.commitizen

"config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog"
    }
  }

或者，在項目根目錄下新建一個 .czrc 文件，內容設置爲

{
  "path": "cz-conventional-changelog"
}

如今運行 git cz 效果以下：

cz-customizable 自定義中文配置

經過上面的截圖能夠看到，提交的配置選項都是英文的，若是想改爲中文的，可使用 cz-customizable 適配器。

運行下面的命令，注意以前已經初始化過一次了，此次再初始化，須要加 --force 覆蓋

npm install cz-customizable --save-dev

commitizen init cz-customizable --save-dev --save-exact --force

如今 package.json 中 config.commitizen 字段爲：

"config": {
    "commitizen": {
      "path": "./node_modules/cz-customizable"
    }
  }

cz-customizable 文檔中說明了查找配置文件的方式有三種，咱們按照第一種，在項目根目錄建立一個 .cz-config.js 的文件。按照給出的示例 cz-config-EXAMPLE.js 編寫咱們的 config。 commit-type 能夠參考 conventional-commit-types 。

能夠點擊查看我配置好的文件 qiqihaobenben/commitizen-git/.cz-config.js ，裏面中詳細的註釋。

commitlint 校驗提交

Commitizen 文檔中開始就介紹到，Commitizen 能夠在觸發 git commit 鉤子以前就能給出提示，可是也明確表示提交時對 commit messages 的校驗也是頗有用的。畢竟即便用了 Commitzen，也是能繞過去，因此提交最後的校驗很重要。

commitlint 能夠檢查 commit messages 是否符合常規提交格式，須要一份校驗配置，推薦 @commitlint/config-conventional 。

npm i --save-dev @commitlint/config-conventional @commitlint/cli

在項目根目錄建立 commitlint.config.js 文件並設置校驗規則：

module.exports = {
  extends: ["@commitlint/config-conventional"],
  // rules 裏面能夠設置一些自定義的校驗規則
  rules: {},
};

在項目中安裝 husky ，並在項目根目錄新建 husky.config.js 文件，加入如下設置：

// 安裝 husky
npm install --save-dev husky


// husky.config.js 中加入如下代碼
module.exports = {
  "hooks": {
    "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
  }
}

注意：由於 @commitlint/config-conventional 校驗規則遵循 Angular 的規範，因此咱們在用 cz-customizable 自定義中文配置時，是按照給出的符合 Angular 規範的示例 cz-config-EXAMPLE.js 編寫 .cz-config.js 的。可是若是你自定義的 Commitizen 配置不符合 Angular 規範，可使用 commitlint-config-cz 設置校驗規則。（推薦仍是按照 Angular 規範進行 cz-customizable 自定義配置）

// 安裝 commitlint-config-cz
npm install commitlint-config-cz --save-dev


// commitlint.config.js 改成
module.exports = {
  extends: [
    'cz'
  ]
};

git commit 觸發 git cz

在提交的時候，咱們都習慣了 git commit ，雖然換成 git cz 不難，可是若是讓開發者在 git commit 時無感知的觸發 git cz 確定是更好的，
並且也能避免不熟悉項目的人直接 git commit 提交一些不符合規範的信息。

咱們能夠在 husky.config.js 中設置：

"hooks": {
  "prepare-commit-msg": "exec < /dev/tty && git cz --hook || true",
}

注意：在 window 系統，可能須要在 git base 中才能生效。

生成 CHANGELOG

standard-version
是一個使用 semver 和 conventional-commits 支持生成 CHANGELOG 進行版本控制的實用程序。
standard-version 不僅是能生成 CHANGELOG , 還能根據 commit 的 type 來進行版本控制。

// 安裝 standard-verison
npm i --save-dev standard-version

// 在 package.json 中的 scripts 加入 standard-version
{
  "scripts": {
    "release": "standard-version"
  }
}

示例項目

能夠查看 commitizen-git ，裏面概括了快速配置 Commitizen 友好倉庫的步驟。
差很少三五分鐘就能搞定。

能夠看一下配置完後，執行 git commit 的效果。

擴展

更復雜的自定義提示

cz-customizable 中自定義配置項一般狀況是夠用的，
commitlint 中校驗的規則基本上也是夠用的，可是會有比較硬核的開發者會以爲仍是不夠，還要更多。好比一些 prompt 更加自定義，
提交時詢問的 question 添加更多的邏輯，好比能夠把一些重要的字段校驗提早到 Commitizen 中，或者添加更多自定義的校驗。

若是真想這麼幹，那就去 fork 一份 cz-conventional-changelog 或者 cz-customizable 來改，
或者直接本身寫一個 adapter。