個(gè)人博客及創(chuàng)作索引頁正在制作中勃教，此處僅釋出本地第一大版本兄墅。原文檔基于 Hexo 及相關(guān)插件，不兼容于此處的格式暫不統(tǒng)一修復(fù)晃酒。

《【翻譯】如何編寫 Git 提交消息》^[1]的簡體中文翻譯版本對應(yīng)原文為 How to Write a Git Commit Message 表牢，原作者為 Chris Beams 。請注意：

• 正文格式盡可能與原網(wǎng)頁保持一致贝次；
• 譯者注將以腳注 (footnote) 的形式呈現(xiàn)崔兴，且其內(nèi)容應(yīng)以”譯者注：“起始；
• 原文中若有文內(nèi)跳轉(zhuǎn)超鏈接蛔翅，如無必要敲茄，將直接去除，且不在譯文中作進(jìn)一步說明山析；
• 原文中若有翻譯后難以傳達(dá)作者寫作意圖的詞句　(通常是命令堰燎，或由源語言的特殊性質(zhì)等原因?qū)е?　，此時(shí)將不再翻譯笋轨，且不在譯文中作進(jìn)一步說明秆剪。

翻譯文本將從隨后的分隔線開始展示。

如何編寫 Git 提交信息

原作者： Chris Beams
原文創(chuàng)作日期： 2014 年 8 月 31 日

提交消息很重要爵政。這里將展示如何寫好它們仅讽。

圖1 信息量遞減的提交消息

引子：為什么好的提交消息很重要

如果你曾隨意地瀏覽過一些 Git 倉庫，你很可能會發(fā)現(xiàn)它們的提交消息或多或少有些雜亂钾挟。例如洁灵，你可以看看我早期提交給 Spring 的一些 Gem^[2] 的日志：

$ git log --oneline -5 --author cbeams --before "Fri Mar 26 2009"

e5f4b49 Re-adding ConfigurationPostProcessorTests after its brief removal in r814. @Ignore-ing the testCglibClassesAreLoadedJustInTimeForEnhancement() method as it turns out this was one of the culprits in the recent build breakage. The classloader hacking causes subtle downstream effects, breaking unrelated tests. The test method is still useful, but should only be run on a manual basis to ensure CGLIB is not prematurely classloaded, and should not be run as part of the automated build.
2db0f12 fixed two build-breaking issues: + reverted ClassMetadataReadingVisitor to revision 794 + eliminated ConfigurationPostProcessorTests until further investigation determines why it causes downstream tests to fail (such as the seemingly unrelated ClassPathXmlApplicationContextTests)
147709f Tweaks to package-info.java files
22b25e0 Consolidated Util and MutableAnnotationUtils classes into existing AsmUtils
7f96f57 polishing

呀！再比較一下同一個(gè)倉庫近期的一些提交的日志：

$ git log --oneline -5 --author pwebb --before "Sat Aug 30 2014"

5ba3db6 Fix failing CompositePropertySourceTests
84564a0 Rework @PropertySource early parsing logic
e142fd1 Add tests for ImportSelector meta-data
887815f Update docbook dependency and generate epub
ac8326d Polish mockito usage

你更想去閱讀哪一種呢等龙？

前者的提交消息在長度和形式上各不相同处渣，而后者更加精準(zhǔn)和一致伶贰；前者是自然而然的結(jié)果，而后者絕不會是碰巧寫成的罐栈。

當(dāng)許多提交日志類似于前者的倉庫隨處可見時(shí)黍衙，也有一些例外存在。 Linux 內(nèi)核和 Git 自身的源碼正是良好的范例荠诬±欧或是看看 Spring Boot 或由 Tim Pope 管理的倉庫。

這些倉庫的貢獻(xiàn)者們知道柑贞，一個(gè)經(jīng)過精心打磨的 Git 提交消息是將一個(gè)更改與其他開發(fā)者 (以及未來的自己) 交流其來龍去脈的最好方式^[3]方椎。一個(gè) diff 的輸出結(jié)果將告訴你什么改變了，而只有提交消息能恰當(dāng)?shù)馗嬖V你為什么改變了钧嘶。 Peter Hutterer 將這個(gè)觀點(diǎn)表達(dá)得很好：

重新確定一段代碼的上下文是浪費(fèi)的棠众。我們不能完全避免它，因此我們應(yīng)當(dāng)努力去[竭盡]所能減少這種情況的發(fā)生有决。提交消息能準(zhǔn)確地做到這一點(diǎn)闸拿，所以一條提交消息能夠展示出一位開發(fā)者是不是好的協(xié)作者。^[4]

如果你還沒有很多思路來編寫良好的 Git 提交消息书幕，這或許說明你沒有花費(fèi)很多時(shí)間使用 git log 命令和相關(guān)的工具新荤。這里有一個(gè)殘酷的循環(huán)：因?yàn)樘峤粴v史是缺少結(jié)構(gòu)和一致性的，某個(gè)人不會花費(fèi)很多時(shí)間使用或關(guān)心它台汇。并且因?yàn)樗槐皇褂没蜿P(guān)心苛骨，它將始終缺少結(jié)構(gòu)和一致性。

然而苟呐，被維護(hù)得很好的日志是一種優(yōu)美和實(shí)用的東西痒芝，這會讓 git blame 、revert 牵素、rebase 吼野、log 、shortlog 和其他子命令充滿活力两波，會給回顧其他人的提交和 pull requests 帶來一些價(jià)值——并且它們突然能被獨(dú)立地完成瞳步。理解幾個(gè)月或幾年前一些事情為什么發(fā)生將不但變得可能，還將變得高效腰奋。

一個(gè)項(xiàng)目能否取得長遠(yuǎn)的成功 (相較于其他因素) 不但取決于其可維護(hù)性如何单起，還在于一個(gè)維護(hù)者是否沒有多少比日志更加有力的工具了。我們值得花費(fèi)一些時(shí)間來學(xué)習(xí)如何適切地維護(hù)項(xiàng)目的日志劣坊。起初維護(hù)日志時(shí)可能的困境不久就會轉(zhuǎn)變?yōu)榱?xí)慣嘀倒，并最終成為所有參與者自豪感和生產(chǎn)力的源泉。

在這篇文章中，我將會告訴你保持一份健康的提交歷史的最基礎(chǔ)的要素：如何編寫一條獨(dú)立的提交消息测蘑。還有其他我在這里不會提及的重要習(xí)慣灌危，比如說統(tǒng)整提交^[5]，或許我會在后續(xù)的投稿中談到它們碳胳。

大多數(shù)編程語言都有著已經(jīng)成形的慣例勇蝙，它們構(gòu)建了符合語言習(xí)慣的風(fēng)格，就像命名挨约、格式等等^[6]味混。當(dāng)然，這些慣例有諸多變種诫惭，但大部分開發(fā)者都認(rèn)同專注于其中一種的情形遠(yuǎn)優(yōu)于每個(gè)人各自選用一種造成的混亂局面翁锡。

一個(gè)團(tuán)隊(duì)對待提交日志的方式應(yīng)當(dāng)沒有絲毫不同。為了創(chuàng)建一份實(shí)用的修訂歷史夕土，團(tuán)隊(duì)?wèi)?yīng)該首先在至少符合以下三點(diǎn)的提交消息慣例上達(dá)成共識：

風(fēng)格馆衔。標(biāo)記語言的句法^[7]，折行的間隔怨绣，語法^[8]哈踱，大小寫，標(biāo)點(diǎn)符號梨熙。將這些都明確給出，去除猜測刀诬，并且讓一切都盡可能簡單咽扇。最終的結(jié)果將會是一份格外一致的日志——不僅閱讀起來很愉悅，而且實(shí)際上的確能被定期閱讀^[9]陕壹。

內(nèi)容质欲。提交消息的主體 (如果有的話) 應(yīng)該包含什么信息？什么是不能包含的糠馆？

元數(shù)據(jù)嘶伟。諸如 issue 的追蹤編號^[10]、 pull request 的編號應(yīng)當(dāng)如何被提及又碌？

萬幸的是九昧，已經(jīng)有一些成形的慣例來創(chuàng)建一條符合語言習(xí)慣的 Git 提交消息。的確毕匀，這些都假定在特定的 Git 命令運(yùn)作的方式下铸鹰。這里沒有你需要重新發(fā)明的地方，只要遵循下方的七條規(guī)則皂岔，你就推開了像專家一樣提交的大門蹋笼。

編寫好的 Git 提交消息的七條規(guī)則

請謹(jǐn)記：這些都已被提出過了。

1. 用一個(gè)空行分隔標(biāo)題和主體；
2. 標(biāo)題控制在 50 個(gè)字符以內(nèi)剖毯；
3. 標(biāo)題的首字母大寫圾笨；
4. 標(biāo)題的末尾不要寫句號；
5. 標(biāo)題使用祈使語氣逊谋；
6. 主體每 72 個(gè)字符折行擂达；
7. 用主體解釋做了什么和為什么，而不是如何做到涣狗。

例如：

Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space, with blank lines in between, but conventions
   vary here

If you use an issue tracker, put references to them at the bottom,
like this:

Resolves: #123
See also: #456, #789

1. 用一個(gè)空行分隔標(biāo)題和主體

根據(jù) git commit 命令的幫助頁面：

盡管不是必須的谍婉，一個(gè)好主意是，提交消息以一行簡短的 (少于 50 個(gè)字符) 概括這個(gè)更改的文字為開始镀钓，緊接著是一個(gè)空行穗熬，隨后是一段更詳細(xì)的描述。整段文本的首行將被認(rèn)作為提交的標(biāo)題丁溅，那個(gè)標(biāo)題將貫穿整個(gè) Git^[11] 唤蔗。例如， Git-format-patch(1) 將提交轉(zhuǎn)變?yōu)猷]件窟赏，它將提交的標(biāo)題作為郵件的主題妓柜，將剩余的提交內(nèi)容作為郵件的主體。

首先涯穷，不是每一次提交都需要標(biāo)題和主體棍掐。有時(shí)一行也很好，尤其是當(dāng)更改很簡單以至于進(jìn)一步的闡釋都不必要的時(shí)候拷况。例如：

Fix typo in introduction to user guide

沒有什么是需要解釋的了作煌。如果讀者想知道這個(gè)拼寫錯誤是什么，直接看這個(gè)更改本身即可赚瘦，換句話說使用 git show 粟誓、 git diff 或 git log -p 。

如果你想用命令提交起意，給 git commit 命令添加 -m 選項(xiàng)是很容易的：

$ git commit -m"Fix typo in introduction to user guide"

然而鹰服，當(dāng)一個(gè)提交需要一點(diǎn)解釋和上下文時(shí)，你需要編寫它的主體揽咕。例如：

Derezz the master control program

MCP turned out to be evil and had become intent on world domination.
This commit throws Tron's disc into MCP (causing its deresolution)
and turns it back into a chess game.

用 -m 選項(xiàng)來寫提交消息的主體不是很容易悲酷，你最好在一個(gè)合適的文本編輯器中編寫它。如果你還沒有一個(gè)編輯器亲善，使用 Git 命令行來設(shè)置舔涎，參閱 Pro Git 的這一節(jié)。

在任何情形下逗爹，標(biāo)題和主體之間的間隔都能在瀏覽日志時(shí)得到回報(bào)亡嫌。這里是完整的日志：

$ git log
commit 42e769bdf4894310333942ffc5a15151222a87be
Author: Kevin Flynn <kevin@flynnsarcade.com>
Date:   Fri Jan 01 00:00:00 1982 -0200

 Derezz the master control program

 MCP turned out to be evil and had become intent on world domination.
 This commit throws Tron's disc into MCP (causing its deresolution)
 and turns it back into a chess game.

現(xiàn)在執(zhí)行 git log --oneline 嚎于，這會僅輸出標(biāo)題行：

$ git log --oneline
42e769 Derezz the master control program

或者是執(zhí)行 git shortlog ，這會按照用戶給提交分組挟冠，為了簡潔于购，同樣會僅輸出標(biāo)題行：

$ git shortlog
Kevin Flynn (1):
      Derezz the master control program

Alan Bradley (1):
      Introduce security program "Tron"

Ed Dillinger (3):
      Rename chess program to "MCP"
      Modify chess program
      Upgrade chess program

Walter Gibbs (1):
      Introduce protoype chess program

也有一些 Git 中的其他上下文，它們的標(biāo)題行和主體的區(qū)別被打破了——但它們都無法在二者之間不空行時(shí)做得合適^[12]知染。

2. 標(biāo)題控制在 50 個(gè)字符以內(nèi)

50 個(gè)字符不是硬性限制肋僧，只是一個(gè)經(jīng)驗(yàn)法則。將標(biāo)題行控制在這個(gè)長度能保證它們是可讀的控淡，并且能強(qiáng)迫作者花一些時(shí)間思考如何最簡潔地解釋將要發(fā)生什么嫌吠。

提示：如果你難以概括你提交的內(nèi)容，或許是因?yàn)槟阋淮翁峤涣颂嗟母牟籼俊Ｅψ龅?a target="_blank">原子級提交^[13] (另一篇投稿的話題) 吧辫诅。

GitHub 的用戶界面全面地意識到了這些慣例。例如涧狮，它會在你的標(biāo)題行超過 50 個(gè)字符時(shí)警告你：

圖2 GitHub 的字?jǐn)?shù)警告

并且會截?cái)喑^ 72 個(gè)字符的標(biāo)題行炕矮，后續(xù)用省略號代替：

圖3 GitHub 的字?jǐn)?shù)超限截?cái)?/div>

因此，爭取限制在 50 個(gè)字符以內(nèi)者冤，并把 72 個(gè)字符當(dāng)作是硬性限制肤视。

3. 標(biāo)題的首字母大寫

這就跟聽起來一樣簡單。所有的標(biāo)題行的首字母都需要大寫涉枫。

例如邢滑，用：

• Accelerate to 88 miles per hour

來替代：

• accelerate to 88 miles per hour

4. 標(biāo)題的末尾不要寫句號

句末標(biāo)點(diǎn)在標(biāo)題中時(shí)無關(guān)緊要的。另外愿汰，當(dāng)你想要控制 50 個(gè)字符時(shí)困后，空格是很珍貴的。

例如尼桶，用：

• Open the pod bay doors

來替代：

• Open the pod bay doors.

5. 標(biāo)題使用祈使語氣

祈使語氣意思就是“說出或?qū)懗鲱愃泼罨蛑甘镜臇|西”。以下是一些例子：

• 清理你的房間
• 關(guān)上這扇門
• 拿走垃圾

你正在閱讀的七條規(guī)則的每一條都是用祈使語氣寫成的　(“主體每　72　個(gè)字符折行”以及其他的)　锯仪。

祈使語氣聽起來有一些失禮泵督，這就是為什么我們不常使用，但是這對于　Git 提交的標(biāo)題來說很完美庶喜，其中一個(gè)原因是 Git 自身以你的名義創(chuàng)建提交時(shí)都是使用祈使語氣小腊。

例如，使用 git merge 后的默認(rèn)提交消息即是：

Merge branch 'myfeature'

還有使用 git revert 后：

Revert "Add the thing with the stuff"

This reverts commit cc87791524aedd593cff5a74532befe7ab69ce9d.

或者是在 GitHub 的Pull Request 界面點(diǎn)擊 “Merge” 按鈕時(shí)：

Merge pull request #123 from someuser/somebranch

因此久窟，當(dāng)你用祈使語氣編寫提交消息時(shí)秩冈，你就是在遵守 Git 內(nèi)置的慣例。例如：

• Refactor subsystem X for readability
• Update getting started documentation
• Remove deprecated methods
• Release version 1.0.0

起初這樣寫可能顯得有些蠢斥扛。我們更常用陳述語氣說話入问，這種語氣都是用于描述事實(shí)丹锹，這就是為什么提交消息很多都像這樣結(jié)束了：

• Fixed bug with Y
• Changing behavior of X

并且有時(shí)提交消息寫起來就像是它們的內(nèi)容的描述：

• More fixes for broken stuff
• Sweet new API methods

為了去除任何困惑，這里是一條簡單的規(guī)則來讓你每次都能做對：

一個(gè)合適的 Git 提交的標(biāo)題應(yīng)當(dāng)總是能完成如下的句子：

• 如果被應(yīng)用了芬失，這個(gè)提交將會這是你的標(biāo)題

例如：

• If applied, this commit will refactor subsystem X for readability
• If applied, this commit will update getting started documentation
• If applied, this commit will remove deprecated methods
• If applied, this commit will release version 1.0.0
• If applied, this commit will merge pull request #123 from user/branch

注意到對于非祈使語氣楣黍，這是不能成功的：

• If applied, this commit will fixed bug with Y
• If applied, this commit will changing behavior of X
• If applied, this commit will more fixes for broken stuff
• If applied, this commit will sweet new API methods

記住：祈使語氣的使用僅對標(biāo)題很重要棱烂。在寫主體時(shí)租漂，你可以放松這條規(guī)定。

6. 主體每 72 個(gè)字符折行

Git 從來不會自動折行颊糜。當(dāng)你編寫一個(gè)提交的主體時(shí)哩治，你需要注意到它的右邊界，并手動折行衬鱼。

折行的推薦值是 72 個(gè)字符业筏，因此 Git 在大體上將對 80 個(gè)字符以內(nèi)的內(nèi)容保持原樣，有足夠的空間用于縮進(jìn)排版馁启。

一個(gè)好的文本編輯器能幫到你驾孔。 Vim 的配置很容易，例如在編寫 Git 提交消息時(shí)在 72 個(gè)字符處折行惯疙。然而翠勉，在傳統(tǒng)意義上， IDE 對于智能地支持提交消息的折行很糟糕 (盡管 IntelliJ IDEA 在最近的版本中終于做得比以前好了) 霉颠。

7. 用主體解釋做了什么和為什么对碌，而不是如何做到

這里的一條來自 Bitcoin Core 的提交 是解釋更改了什么和為什么的最佳范例：

commit eb0b56b19017ab5c16c745e6da39c53126924ed6
Author: Pieter Wuille <pieter.wuille@gmail.com>
Date:   Fri Aug 1 22:57:55 2014 +0200

   Simplify serialize.h's exception handling

   Remove the 'state' and 'exceptmask' from serialize.h's stream
   implementations, as well as related methods.

   As exceptmask always included 'failbit', and setstate was always
   called with bits = failbit, all it did was immediately raise an
   exception. Get rid of those variables, and replace the setstate
   with direct exception throwing (which also removes some dead
   code).

   As a result, good() is never reached after a failure (there are
   only 2 calls, one of which is in tests), and can just be replaced
   by !eof().

   fail(), clear(n) and exceptions() are just never called. Delete
   them.

看一看它的完整的 diff 信息，思考這位作者在此時(shí)此地花費(fèi)時(shí)間提供代碼的上下文節(jié)約了其他和未來的提交者多少時(shí)間蒿偎。如果他沒有做到朽们，這次提交將很可能會永遠(yuǎn)被遺忘。

在大多數(shù)情況下诉位，你可以省去這個(gè)更改如何被做出的細(xì)節(jié)骑脱。在這點(diǎn)上，代碼通常能自我解釋 (如果這段代碼如此復(fù)雜以至于它需要用枯燥的語言來解釋苍糠，那就是源代碼注釋應(yīng)該做的事情了) 叁丧。只是專注于首先明確更改的原因——你在更改之前所做的事 (以及出現(xiàn)了什么錯誤) ，它們現(xiàn)在如何工作的岳瞭，以及為什么你決定用你的方式解決這個(gè)問題^[14]拥娄。

未來感謝你的維護(hù)者可能就是你自己！

提示

學(xué)著熱愛命令行瞳筏。把 IDE 拋在腦后稚瘾。

處于諸多原因，比如說 Git 子命令的存在姚炕，擁抱命令行是一種明智之舉摊欠。 Git 有著令人瘋狂的力量丢烘， IDE 亦然，但這兩者體現(xiàn)在不同的方面上凄硼。我每天都使用一款 IDE (IntelliJ IDEA) 铅协，也廣泛地使用其他的 (Eclipse) ，但我還從沒有見過哪款 IDE 的 Git 集成能比得上簡單有力的命令行 (一旦你意識到了這點(diǎn)) 摊沉。

某些 Git 相關(guān)的 IDE 功能是無價(jià)的[^15]狐史，就像當(dāng)你刪除文件時(shí)執(zhí)行 git rm ，在你重命名文件的時(shí)候用 git 執(zhí)行正確的命令说墨。而當(dāng)你開始試著用 IDE 提交骏全、合并、 rebase 或分析高深莫測的歷史記錄時(shí)尼斧，一切都會崩潰姜贡。

當(dāng)支配 Git 的全部法力之日到來之時(shí)，一切都只剩下命令行棺棵。

記住不論你是使用 Bash 楼咳、 zsh 還是 PowerShell ，都有 Tab 自動補(bǔ)全腳本來減輕不少記憶子命令和開關(guān)的痛苦烛恤。

閱讀 Pro Git

Pro Git 在網(wǎng)上可以免費(fèi)閱讀母怜，并且它很美妙。好好利用它吧缚柏！

題圖提供者： xkcd

---

【完】

腳注

---

1. 譯者注：”提交消息“原文為 ”commit message“ 苹熏，下同。 ?

2. 譯者注： Spring 庫的插件名為 “Gem” 币喧。 ?

3. 譯者注：原文為 ”The contributors to these repositories know that a well-crafted Git commit message is the best way to communicate context about a change to fellow developers (and indeed to their future selves)“ 轨域。 ?

4. 譯者注：原文為 ”Re-establishing the context of a piece of code is wasteful. We can’t avoid it completely, so our efforts should go to <u>reducing it</u> [as much] as possible. Commit messages can do exactly that and as a result, a commit message shows whether a developer is a good collaborator“ 。 ?

5. 譯者注：原文為 “Most programming languages have well-established conventions as to what constitutes idiomatic style, i.e. naming, formatting and so on” 杀餐。 ?

6. 譯者注：原文為 “syntax” 干发。 ?

7. 譯者注：原文為 “grammar” 。 ?

8. 譯者注：原文為 “The end result will be a remarkably consistent log that’s not only a pleasure to read but that actually does get read on a regular basis” 史翘。 ?

9. 譯者注：原文為 “issue tracking IDs” 枉长。 ?

10. 譯者注：原文為 “ The text up to the first blank line in a commit message is treated as the commit title, and that title is used throughout Git” 。 ?

11. 譯者注：原文為 “There are a number of other contexts in Git where the distinction between subject line and body kicks in—but none of them work properly without the blank line in between” 恶座。 ?

12. 譯者注：原文為 “atomic commits” 搀暑。 ?

13. 譯者注：原文為 “Just focus on making clear the reasons why you made the change in the first place—the way things worked before the change (and what was wrong with that), the way they work now, and why you decided to solve it the way you did” 沥阳。 ?

14. 譯者注：原文為 “Certain Git-related IDE functions are invaluable” 跨琳。 ?