（轉）Git 提交的正確姿式：Commit message 編寫指南

時間 2019-11-11

標籤 git 提交正確 commit message 編寫指南欄目 Git 简体版

原文原文鏈接

Git 每次提交代碼，都要寫 Commit message（提交說明），不然就不容許提交。java

$ git commit -m "hello world"

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

若是一行不夠，能夠只執行git commit，就會跳出文本編譯器，讓你寫多行。github

$ git commit

基本上，你寫什麼都行（這裏，這裏和這裏）。shell

可是，通常來講，commit message 應該清晰明瞭，說明本次提交的目的。npm

目前，社區有多種 Commit message 的寫法規範。本文介紹Angular 規範（見上圖），這是目前使用最廣的寫法，比較合理和系統化，而且有配套的工具。json

1、Commit message 的做用

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

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

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

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

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

好比，下面的命令僅僅顯示本次發佈新增長的功能。

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

（3）能夠直接從commit生成Change log。

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

2、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：重構（即不是新增功能，也不是修改bug的代碼變更）
test：增長測試
chore：構建過程或輔助工具的變更

若是type爲feat和fix，則該 commit 將確定出如今 Change log 之中。其餘狀況（docs、chore、style、refactor、test）由你決定，要不要放入 Change log，建議是不要。

（2）scope

scope用於說明 commit 影響的範圍，好比數據層、控制層、視圖層等等，視項目不一樣而不一樣。

（3）subject

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

以動詞開頭，使用第一人稱如今時，好比change，而不是changed或changes
第一個字母小寫
結尾不加句號（.）

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）使用第一人稱如今時，好比使用change而不是changed或changes。

（2）應該說明代碼變更的動機，以及與之前行爲的對比。

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）關閉 Issue

若是當前 commit 針對某個issue，那麼能夠在 Footer 部分關閉這個 issue 。

Closes #234

也能夠一次關閉多個 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 <hash>.，其中的hash是被撤銷 commit 的 SHA 標識符。

若是當前 commit 與被撤銷的 commit，在同一個發佈（release）裏面，那麼它們都不會出如今 Change log 裏面。若是二者在不一樣的發佈，那麼當前 commit，會出如今 Change log 的Reverts小標題下面。

3、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。

4、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

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.json的scripts字段。

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

之後，直接運行下面的命令便可。

$ npm run changelog

本文轉載自阮一峯博客

相關連接

Git 的詳細介紹：點擊查看
Git 的下載地址：點擊下載

碼雲極速下載/Git

Star 0 | Fork 0

Git是一個開源的分佈式版本控制系統，用以有效、高速的處理從很小到很是大的項目版本管理。