Git提交的正確姿勢:Commit message 和 Change log 編寫指南

2021-02-20 Android程式設計師

Git 每次提交代碼，都要寫 Commit message（提交說明），否則就不允許提交。

$ git commit -m "hello world"

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

如果一行不夠，可以只執行git commit，就會跳出文本編譯器，讓你寫多行。

$ git commit

基本上，你寫什麼都行，可參考如下文章：

http://www.commitlogsfromlastnight.com

http://blog.no-panic.at/2014/10/20/funny-initial-git-commit-messages/

http://whatthecommit.com


但是，一般來說，commit message 應該清晰明了，說明本次提交的目的。


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

一、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 是發布新版本時，用來說明與上一個版本差異的文檔，詳見後文。


二、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：修補bugdocs：文檔（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' optionThis reverts commit 667ecc1654a317a13331b17617d973392f415f02.

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

如果當前 commit 與被撤銷的 commit，在同一個發布（release）裡面，那麼它們都不會出現在 Change log 裡面。如果兩者在不同的發布，那麼當前 commit，會出現在 Change log 的Reverts小標題下面。

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


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

五、生成 Change log

如果你的所有 Commit 都符合 Angular 格式，那麼發布新版本時， Change log 就可以用腳本自動生成。

例1：https://github.com/ajoslin/conventional-changelog/blob/master/CHANGELOG.md
例2：https://github.com/karma-runner/karma/blob/master/CHANGELOG.md
例3：https://github.com/btford/grunt-conventional-changelog/blob/master/CHANGELOG.md

生成的文檔包括以下三個部分。

New featuresBug fixesBreaking 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

如果喜歡這篇文章，記得點讚與分享給好友。

如果你還想了解更多Android開發最佳實踐、經驗分享、最好用的工具與服務，技術前沿，請長按下方二維碼或搜索微信公眾號:AndroidTrending關注我，我會繼續保持精品。

相關焦點

  • Git 提交的正確姿勢:Commit message 編寫指南
    Git 每次提交代碼，都要寫 Commit message（提交說明），否則就不允許提交。
  • Git Commit Log 的小型團隊最佳實踐
    注意：2016年1月6日，阮一峰老師寫了一篇《Commit message 和 Change log 編寫指南》（http://www.ruanyifeng.com/blog/2016/01/commit_message_change_log.html），本文主要來源於這篇文章，只是針對我們的團隊，進行了一些改造和簡化，以及對一些阮老師沒有提及的細小之處進行了指出
  • 優雅的提交你的 Git Commit Message
    正文從這開始～commit message 是開發的日常操作, 寫好 log 不僅有助於他人 review, 還可以有效的輸出 CHANGELOG, 對項目的管理實際至關重要, 但是實際工作中卻常常被大家忽略.希望通過本文, 能夠幫助大家重視和規範 commit message 的書寫.
  • GIT實踐之生成規範的commit message
    以動詞開頭，使用第一人稱現在時，比如change，而不是changed或changes第一個字母小寫結尾不加句號（.）三、Commitizenmac如果沒有安裝npm命令，可以用brew命令下載以後，凡是用到git commit命令，一律改為使用git cz。這時，就會出現選項，用來生成符合格式的 Commit message。
  • 如何寫一個易讀的git commit message
    show or git diff or git log -p.Here’s the full log entry:$ git logcommit 42e769bdf4894310333942ffc5a15151222a87beAuthor: Kevin Flynn <kevin@flynnsarcade.com>Date: Fri Jan 01 00:00:00 1982 -0200 Derezz
  • git基本用法和log查看
    每次我們add後有段文字提示 (use "git reset HEAD <file>……" to unstage)直接git reset HEAD file恢復add之前的狀態git commit命令git commit -m 'message' 最常用的提交命令。
  • 如何規範你的Git commit?
    本文分享在git commit規範建設上的實踐，規定了commit message的格式，並通過webhook在提交時進行監控，避免不規範的代碼提交。文末福利：在線IT技能測試。Git每次提交代碼都需要寫commit message，否則就不允許提交。
  • 您必須知道的 Git 分支開發規範,附 Git 常用命令大全!
    但是好的日誌規範 commit messages 編寫有幫助到我們，它也反映了一個開發人員是否是良好的協作者。編寫良好的 Commit messages 可以達到3個重要的目的：目前，社區有多種 Commit message 的寫法規範。來自 Github 上的 Angular 規範是目前使用最廣的寫法，比較合理和系統化。
  • 有意思的 git-log
    今天要說的便是常用的 git log 命令。先看幾個慄子以 React-Native 代碼為例，演示幾個有意思的 git-log 命令。理解 git loggit log 詳細記錄了所有開發者在項目中的貢獻情況，包括作者的信息、提交的內容（與上一次的差異對比 patch），還添加了一些額外的諸如時間、id（commit sha1）等內容。它就像是一個資料庫，提供了很多很多參數可以被重新梳理、查詢。
  • Git進階與技巧
    技巧恢復刪除分支中指定的提交# 1、使用 git reflog 查看提交記錄，找到需要回復的 commit$ git reflog# 2、使用 cherry-pick 指定一個 commit，合併進當前分支$ git cherry-pick <commit># 如果刪除提交記錄較多，可以創建新的分支
  • Git 提交錯了不用慌,這三招幫你修改記錄
    有的時候我們會突然發現某個地方需要修改，最常見的某個不應該被提交的文件被提交了進來。我們希望它不只是在後續的版本當中不再出現，而是希望整個從 git 倉庫當中移除掉。這個時候我們就需要修改 git 之前的歷史記錄。這個時候應該怎麼辦呢？不要著急，git 當中有很多的手段可以修改之前的歷史提交記錄。
  • 【譯】10 個最有用的 git log 技巧
    It condenses each commit to a line and has only minimal information like shorter commit hash, commit message.（這條命令可以幫助你以簡潔的方式查看提交記錄。
  • 使用commit提交大文件無法推送到遠程庫解決問題
    into previous commit# f, fixup <commit> = like "squash", but discard this commit's log message# x, exec <command> = run command (the rest of the line) using shell# b, break = stop here (continue
  • Askgit:利用熟悉的SQL語句挖掘git倉庫的信息
    如果無法確定它的安裝位置，請檢查是否已GOPATH正確設置，然後它將以結尾$GOPATH/bin。第一次提交信息我們可以搜索第一次提交時候的相關信息，包括提交人，commit信息，郵箱地址，提交時間等：askgit "select message, author_name, author_email, author_when from commits order by committer_when asc limit 1"顯示askgit倉庫第一次提交到時候是
  • git commit emoji 使用指南
    README.md執行 git commit 時使用 emoji 為本次提交打上一個 "標籤", 使得此次 commit 的主要工作得以凸現，也能夠使得其在整個提交歷史中易於區分與查找。截取的 gitmoji 快照:
  • git commit --amend 用法
    當我們想要對上一次的提交進行修改時，我們可以使用 git commit –-amend 命令。git commit –-amend既可以對上次提交的內容進行修改，也可以修改提交說明。>Step3：此時我們發覺我們忘了創建文件 c.txt，而我們認為 c.txt 應該和 a.txt, b.txt 一同提交，而且 a.txt 文件中應該有內容 'a'。
  • Git鮮為人知的四個命令:bisect,blame,reflog和提交範圍
    你要使用git log從歷史中選擇一個commit，那次commit之前的版本你確定是沒有問題。於現在使用git bisect來執行一個二分搜索，找到引入錯誤的commit。如果聽起來太抽象，我們來實例展示：假設我這有一個項目，是關於記單詞的，每天遞增把陌生的單詞存到github的項目中，以便以後複習和存儲你學習生詞的歷史。
  • Git命令解析 - init、add、commit
    回到A倉庫，在git add 的基礎上調用commit生成一個提交。查看對象目錄：和A倉庫直接git commit生成的文件對比，發現其中一個文件名不同。這是由於commit對象中包含執行時間信息，導致生成了不同的哈希編碼。
  • Oh Shit, Git!?!
    git reflog# 你將看到你在 git 上提交的所有改動記錄被列# 了出來，而且囊括了所有的分支，和已被刪除的# commit 哦！git commit --amend# 按照提示修改信息就行啦使用繁瑣的提交信息格式哎呦我去，我不小心把本應在新分支上提交的東西提交到了 master!
  • 這才是真正的Git——Git實用技巧
    stop for amending# s, squash <commit> = use commit, but meld into previous commit# f, fixup <commit> = like "squash", but discard this commit's log message# x, exec <command