Git Commit message編寫指南

一、Commit message 的作用

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

1.提供更多的歷史信息,方便快速瀏覽

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

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

image

2.可以過濾某些commit(比如文檔改動),便於快速查找信息

比如,下面的命令僅僅顯示本次發佈新增加的功能。

git log <last release> HEAD --grep feature

3.可以直接從commit生成Change log

Change Log 是發佈新版本時,用來說明與上一個版本差異的文檔,比如使用conventional-changelog

示意圖

image

二、Commit message 的格式

每次提交,Commit message 都包括三個部分:Header,Body 和 Footer。

<type>(<scope>): <subject>         ----Header

<body>                             ----Body

<footer>                           ----Footer

其中,Header 是必需的,Body 和 Footer 可以省略。

不管是哪一個部分,任何一行都不得超過72個字符(或100個字符)。這是爲了避免自動換行影響美觀。

1.Header

Header部分只有一行,包括三個字段:type(必需)、scope(可選)和subject(必需)。

(1)type

type用於說明 commit 的類別,只允許使用下面8個標識:

  • feat: 新功能
  • fix: 修復問題
  • docs: 修改文檔
  • style: 修改代碼格式,不影響代碼邏輯
  • refactor: 重構代碼,理論上不影響現有功能
  • perf: 提升性能
  • test: 增加修改測試用例
  • revert: 回退
  • chore:構建過程或輔助工具的變動

如果type爲featfix,則該 commit 將肯定出現在 Change log 之中。其他情況(docschorestylerefactortest)由你決定,要不要放入 Change log,建議是不要。

(2)scope[可選]

scope用於說明 commit 影響的範圍,視項目不同而不同。

(3)subject

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

  • 以動詞開頭,使用第一人稱現在時,比如change,而不是changed或changes
  • 第一個字母小寫
  • 結尾不加句號(.)

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

有兩個注意點:

  • 使用第一人稱現在時,比如使用change而不是changed或changes。
  • 應該說明代碼變動的動機,以及與以前行爲的對比。

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

4.Revert

還有一種特殊情況,如果當前 commit 用於撤銷以前的 commit,則必須以revert:開頭,後面跟着被撤銷 Commit 的 Header。

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

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

Body部分的格式是固定的,必須寫成This reverts commit &lt;hash>.,其中的hash是被撤銷 commit 的 SHA 標識符。

如果當前 commit 與被撤銷的 commit,在同一個發佈(release)裏面,那麼它們都不會出現在 Change log 裏面。如果兩者在不同的發佈,那麼當前 commit,會出現在 Change log 的Reverts小標題下面。

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章