1. git commit說明
我們都知道,Git 每次提交代碼,都要寫 Commit message(提交說明),否則就不允許提交,這其實就是規範,但輸入的說明我們可以隨便寫,之前我也會隨便寫,後來看到同事都很規範的寫,就學習了一下。
$ git commit -m "hello world"
上面代碼的-m
參數,就是用來指定 commit mesage 的。
如果一行不夠,可以只執行git commit
,就會跳出文本編輯器,讓你寫多行。
$ git commit
一般來說,commit message 應該清晰明瞭,說明本次提交的目的。而且多人協作的時候,有問題也方便查看提交日誌
列一張我們項目的提交,我是剛開始用有些也不是很規範,當然在gitlab上查看圖形化還是很方便的,對有些習慣用命令行的查看,這種規範就會很有作用了。
這好像是Angular 規範,這是目前使用最廣的寫法,比較合理和系統化,並且有配套的工具。
2. Commit message 作用
格式化的Commit message,有幾個好處。
(1)提供更多的歷史信息,方便快速瀏覽。
比如,下面的命令顯示上次發佈後的變動,每個commit佔據一行。你只看行首,就知道某次 commit 的目的。
$ git log <last tag> HEAD --pretty=format:%s
(2)可以過濾某些commit(比如文檔改動),便於快速查找信息。
比如,下面的命令僅僅顯示本次發佈新增加的功能。
$ git log <last release> HEAD --grep feature
(3)可以直接從commit生成Change log。
Change Log 是發佈新版本時,用來說明與上一個版本差異的文檔,詳見後文。
3. Commit message 的格式規範
每次提交,Commit message 都包括三個部分:Header,Body 和 Footer。
<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>
其中,Header 是必需的,Body 和 Footer 可以省略。
不管是哪一個部分,任何一行都不要有太多字符。這是爲了避免自動換行影響美觀。
3.1 Message Subject(Header)
Header部分只有一行,包括三個字段:type
(必需)、scope
(可選)和subject
(必需)。
(1)type
type
用於說明 commit 的類別,只允許使用下面7個標識。
- feat:新功能()
- fix:修補bug( )
- docs:修改文檔( )
- style: 格式化代碼結構(不影響代碼運行的變動 )
- refactor:重構(即不是新增功能,也不是修改bug的代碼變動,比如重命名變量 )
- chore:構建過程或輔助工具的變動(不會影響代碼運行)
如果type
爲feat
和fix
,則該 commit 將肯定出現在 Change log 之中。其他情況(docs
、chore
、style
、refactor
、test
)由你決定,要不要放入 Change log,建議是不要。
除此之外,還提供了一種表情符號的方式,在標識前再加一個:
就可以顯示了,我喜歡這種方式,有意思還明瞭。
(2)scope
scope
用於定義type
影響的範圍,比如數據層、控制層、視圖層等等,視項目不同而不同。
(3)subject
subject
是 commit 目的的簡短描述,不超過50個字符。
- 以動詞開頭,使用第一人稱現在時,比如
change
,而不是changed
或changes
- 第一個字母小寫
- 結尾不加句號(
.
)
3.2 Body
Body 部分是對本次 commit 的詳細描述,可以分成多行,每行儘量不超過72個字符。下面是一個範例。
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
3.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
3.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
小標題下面。
4. 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。
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
參考:
https://github.com/slashsBin/styleguide-git-commit-message
http://www.ruanyifeng.com/blog/2016/01/commit_message_change_log.html