Git 日志攻臀，又稱為提交日志轰传，或者commit message。也許每個(gè)剛畢業(yè)的程序員初入職場時(shí)辆它，都會(huì)被告知使用 Git 提交代碼時(shí)誊薄，需要注意提交規(guī)范。然而锰茉，提交日志究竟怎么寫呢蔫，才算規(guī)范呢？
「完美日志」編寫規(guī)則
我們在開源社區(qū)中參考了一些相關(guān)資料飒筑，形成了以下若干條基本的GCM（Git Commit Message）編寫規(guī)則片吊。我們也在GitHub上為這些規(guī)則創(chuàng)建了一份副本，可以參考协屡。
GCM001 首行作為「總結(jié)行」俏脊，簡明扼要的總結(jié)提交內(nèi)容
無論是 Kernel 領(lǐng)袖 Torvalds，還是 Vim 骨灰級(jí)玩家 Tim Pope肤晓，都提出了這一點(diǎn)要求爷贫。其中，Tim Pope 建議补憾，該行信息長度應(yīng)該控制在50個(gè)字符以內(nèi)漫萄。
即使 Torvalds 并沒有限制該行信息的長度，但是我們還是要對該長度進(jìn)行控制盈匾。在GCM005中列舉了若干需要用到總結(jié)行的命令和工具卷胯。在這些命令或工具中，如果「總結(jié)行」長度過長威酒，那么顯示效果和閱讀體驗(yàn)將會(huì)大打折扣窑睁。
GCM002 「總結(jié)行」行文使用「祈使句」
如果某次提交，主要是用于修復(fù)某個(gè) Bug葵孤，那么使用英文寫日志担钮， 就應(yīng)該表述為 「Fix Bug」，而不是 「Fixing Bug」或「Fixed Bug」尤仍。如果使用中文箫津，則應(yīng)寫作「修復(fù) Bug」，避免寫作「修復(fù)了 Bug」或者 「已修復(fù) Bug」等形式宰啦。
統(tǒng)一使用「祈使句」苏遥，一方面，可以統(tǒng)一形式赡模；另外祈使句形式的 Git 日志田炭，也能夠與 git merge 和 get revert 自動(dòng)生成的 Git 日志的形式相吻合。
在 GitLab 中漓柑，「總結(jié)行」中還可以使用#XXX來引用 Issue教硫，這里的XXX就是 Issue ID。如果這個(gè)提交和這個(gè) Issue 是位于同一個(gè)項(xiàng)目中的辆布，那么 GitLab 就會(huì)自動(dòng)為你創(chuàng)建一個(gè)指向 Issue 的鏈接瞬矩。
在GitHub中，你甚至可以在「總結(jié)行」中锋玲，使用關(guān)鍵詞關(guān)閉一個(gè)Issue景用。例如「總結(jié)行」中包含「Fix #123」，那么這個(gè)提交一旦被合并至主分支惭蹂，Issue123 將會(huì)被 Close伞插。
GCM003 不在「總結(jié)行」結(jié)尾使用標(biāo)點(diǎn)符號(hào)
「總結(jié)行」的作用，類似于標(biāo)題剿干。因此蜂怎，不需要在總結(jié)行末尾添加標(biāo)點(diǎn)符號(hào)。
GCM004 使用「正文」來描述提交細(xì)節(jié)信息
提交的「正文」置尔，應(yīng)當(dāng)回答以下幾個(gè)問題：
-
WHY這次提交是為了解決什么樣的問題杠步？
- 項(xiàng)目管理者，可能需要通過這個(gè)問題的回答榜轿，來判斷究竟是否要將本次提交合并至 master 分支幽歼；
- 執(zhí)行 Code Review 時(shí)，Reviewers 可以通過這個(gè)問題的回答谬盐，更加迅速地了解本次提交的內(nèi)容甸私，以及剔除不相關(guān)的提交內(nèi)容；
- 當(dāng)我們?yōu)榱丝焖倥挪橐淮我雴栴}的提交時(shí)飞傀，這個(gè)信息也能夠?yàn)槲覀兲峁┖芏嘤袃r(jià)值的參考皇型。
-
HOW這次提交如何解決剛才所提到的問題诬烹？
在更高的層面上，描述一下我們?yōu)榱私鉀Q所提到的問題弃鸦，采取了哪些策略和算法绞吁。例如，「通過在XXX過程中引入一個(gè)XXX對應(yīng)于XXX關(guān)系的哈希表唬格，提高對XXX的索引性能家破，進(jìn)一步解決XXX方面執(zhí)行效率的瓶頸」焊冢」就是一個(gè)很不錯(cuò)的描述汰聋。
當(dāng)然，如果你所采取的做法非常明顯喊积，比如這次提交僅僅是為了修正不規(guī)范的代碼風(fēng)格烹困，或者修正一個(gè)拼寫錯(cuò)誤，你大可省略這一段的描述注服。
當(dāng)然韭邓，如果目前的做法有哪些地方不太妥當(dāng)，或者只是臨時(shí)的解決辦法（Walk Across Solution）溶弟，需要后續(xù)更正女淑，這些內(nèi)容也可以在本段中進(jìn)行描述說明。
-
OTHERS這次提交還包含其他哪些修改辜御？
提交日志是否需要包含這段內(nèi)容鸭你，取決于你的團(tuán)隊(duì)對單次提交所包含的修改內(nèi)容多少的容忍程度。一般來講擒权，Git 鼓勵(lì)我們只做「原子提交」袱巨，即每次提交僅僅只涉及一個(gè)內(nèi)容，只解決一個(gè)問題碳抄。如果單次提交確實(shí)涉及到其他的修改項(xiàng)愉老，可以在本段中列出。但是本著 「原子提交」的原則剖效，其他的修改項(xiàng)不宜過多嫉入，盡量控制在 2 個(gè)以內(nèi)。
此外璧尸，「正文」在行文中咒林，可以使用列表的形式對所闡述的信息分條闡述。列表標(biāo)記可以使用 * 或 - 符號(hào)爷光。這一點(diǎn)和 Markdown 格式非常類似垫竞。
GCM005 「總結(jié)行」與「正文」之間使用「空行分隔」
「空行分隔」用于區(qū)別「總結(jié)行」與「正文」部分，某些命令或工具蛀序，都會(huì)根據(jù)「空行分隔」對提交日志進(jìn)行解析：
-
git format-patch和git send-email命令中欢瞪，「總結(jié)行」將作為郵件標(biāo)題使用活烙，「正文」將作為郵件正文使用； -
git log --oneline遣鼓，git shortlog命令將使用「總結(jié)行」作為提交簡要描述瓣颅，如果沒有「空行分隔」，提交簡要描述中譬正，將會(huì)包含「正文」部分； - 使用
git rebase -i后檬姥，自動(dòng)啟動(dòng)的編輯器中曾我，會(huì)使用「總結(jié)行」作為每個(gè)提交的簡要描述； - 如果 Git 設(shè)置了
merge.summary選項(xiàng)健民，那么當(dāng)執(zhí)行merge操作時(shí)抒巢，Git 將會(huì)匯總來自所有被 merge 的提交的「總結(jié)行」，作為本次 merge 提交的「總結(jié)行」秉犹； -
gitk工具有專門的一欄用于顯示「總結(jié)行」蛉谜； -
GitLab和GitHub在他們的用戶界面總，都專門為「總結(jié)行」做了顯示設(shè)計(jì)崇堵；
GCM006 「正文」中的不同段落使用空行分隔
該原則與 Markdown 的段落分隔方法相似型诚。
GCM007 「正文」每一行的長度控制在 72 個(gè)字符以內(nèi)
在 Git 的設(shè)計(jì)思路中，提交日志的排版鸳劳，換行等工作狰贯，需要日志的編寫者來負(fù)責(zé)處理的。因?yàn)橹挥腥罩咎峤徽呱屠胖谰烤鼓男┑胤叫枰獡Q行涵紊，哪些地方不能換行。Torvalds對此也有解釋：
-
git log命令在顯示提交日志時(shí)幔摸，并不負(fù)責(zé)對日志進(jìn)行分頁換行處理摸柄，所以如何換行比較美觀，需要日志編寫者來考慮處理既忆； - 某些信息驱负，例如編譯器的編譯輸出等，是不能包含換行的尿贫。
為何日志的長度需要限制在 72 個(gè)字符呢电媳？
- 默認(rèn)情況下，
git log命令會(huì)調(diào)用less -S對提交日志進(jìn)行分頁顯示庆亡。因此匾乓，對于常用的寬度為80字符的終端來講，如果你的日志中一行的長度超過80又谋，那么長度超過80的的部分將會(huì)顯示在終端之外拼缝，閱讀起來將會(huì)很不方便娱局。在寬度為80字符的終端中，為了更好的顯示日志內(nèi)容咧七，80個(gè)字符減去左邊可能會(huì)存在的4字符縮進(jìn)衰齐，以及右邊為了保證左右對稱的4字符寬度，就得到了 72 字符的日志長度限制继阻。 - 使用
git format-patch --stdout命令時(shí)耻涛，Git 會(huì)將提交轉(zhuǎn)換成多個(gè)郵件序列。對于純文本格式的郵件瘟檩，為了保證郵件閱讀體驗(yàn)抹缕，一般要保證在考慮了歷史郵件嵌套的情況下，在80個(gè)字符的終端中墨辛，郵件仍然可以較美觀的顯示卓研，因此，對于這個(gè)需求睹簇，72 字符的寬度限制奏赘，仍然是一個(gè)不錯(cuò)的選擇。
GCM008 確保你的提交是「原子提交」
「原子提交」指的是 每個(gè)提交僅包含一個(gè)修改太惠，且必須包含該修改所有的相關(guān)內(nèi)容磨淌。因此，你不可以：
- 提交中混合與提交目的不相關(guān)的提交內(nèi)容垛叨；
- 提交不完整的內(nèi)容伦糯，甚至導(dǎo)致代碼不能正常編譯的內(nèi)容；
- 在一個(gè)較大的修改提交中「隱藏」一些很小的代碼改動(dòng)嗽元。
使用git add -p命令敛纲，可以幫助你較方便的將你的提交整理成一個(gè)個(gè)小的「原子提交」。
