git commit 規范指南

haplake 7年前發布 | 68K 次閱讀 Git 版本控制系統

前言

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

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</pre> 

    有兩個注意點:
     

       
 
    •  
      使用第一人稱現在時，比如使用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.</pre> 

    關閉 Issue
     

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

    Closes #234
     

    Revert
     

    還有一種特殊情況，如果當前 commit 用于撤銷以前的 commit，則必須以revert:開頭，后面跟著被撤銷 Commit 的 Header。
     

    revert: feat(pencil): add 'graphiteWidth' option
    

    • 



This reverts commit 667ecc1654a317a13331b17617d973392f415f02.</pre> 
  
Body部分的格式是固定的，必須寫成 This reverts commit &lt;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 用于檢查 Node 項目的 Commit message 是否符合格式。
 
  
它的安裝是手動的。首先，拷貝下面這個 JS文件 ，放入你的代碼庫。文件名可以取為 validate-commit-msg.js 。
 
  
接著，把這個腳本加入 Git 的 hook。下面是在 package.json 里面使用 ghooks，把這個腳本加為 commit-msg 時運行。
 
  
然后，每次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 格式，那么發布新版本時， 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
 
  
 
 
  
來自：https://segmentfault.com/a/1190000009048911
 
  
 
 本文由用戶 haplake 自行上傳分享，僅供網友學習交流。所有權歸原作者，若您的權利被侵害，請聯系管理員。
 轉載本站原創文章，請注明出處，并保留原始鏈接、圖片水印。
 本站是一個以用戶分享為主的開源技術平臺，歡迎各類分享！