git commit 規範指南

時間 2019-11-06

標籤 git commit 規範指南欄目 Git 简体版

原文原文鏈接

前言

Git 每次提交代碼，都要寫 Commit message（提交說明），不然就不容許提交。可是，通常來講，commit message 應該清晰明瞭，說明本次提交的目的。html

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

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

Commit message 的做用

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

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

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

能夠過濾某些commit（好比文檔改動），便於快速查找信息

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

能夠直接從commit生成Change log。

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

其餘優勢

可讀性好，清晰，沒必要深刻看代碼便可瞭解當前commit的做用。json
爲 Code Reviewing作準備前端框架
方便跟蹤工程歷史框架
讓其餘的開發者在運行 git blame 的時候想跪謝ide
提升項目的總體質量，提升我的工程素質工具

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爲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 部分只用於如下兩種狀況：

不兼容變更

若是當前代碼與上一個版本不兼容，則 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

相關標籤/搜索

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。