[譯] Commit 提交指南

時間 2019-11-07

標籤 commit 提交指南简体版

原文原文鏈接

原文地址：Commit messages guide

原文做者：RomuloOliveira

譯文出自：掘金翻譯計劃

本文永久連接：github.com/xitu/gold-m…

譯者：Mirosalva

校對者：Chorer，zoomdong

一份理解 commit 信息重要性以及如何寫好它們的指導手冊。css

它能夠幫你瞭解什麼是 commit，爲何填寫好的信息說明比較重要，以及提供最佳實踐、計劃和（從新）書寫良好的 commit 歷史的一些建議。html

可參考的語言版本

什麼是「commit」？

簡而言之，commit 就是你本地倉庫中文件的一個快照。和一些人的想法相反，git 不只存儲文件之間的差別，還存儲全部文件的完整版本。對於從一次提交到另外一次提交之間未發生改變的文件，git 僅存儲以前已存的同一份文件的連接。前端

下面的圖片顯示了 git 隨着時間變化如何存儲數據，其中每一個『版本』都是一個 commit：android

爲何 commit 信息很重要？

加快和簡化代碼審查
幫助理解代碼變動
協助解釋僅靠代碼沒法徹底描述的『爲何』
幫助將來的維護者明白變動的緣由以及如何變動，使故障排查和調試更容易

爲了最大化這些好處，咱們可使用下一節描述的一些好的實踐和標準。ios

好的實踐

這些是從個人經驗、網絡文章和其餘指南中收集的一些實踐案例。若是您有其餘實踐(或有不一樣意見)，請儘管隨時打開 Pull Request 並貢獻您的意見。git

使用祈使形式

# 好示例
Use InventoryBackendPool to retrieve inventory backend
複製代碼

# 壞示例
Used InventoryBackendPool to retrieve inventory backend
複製代碼

但爲何要使用祈使形式？github

一個 Commit 信息描述了提到的變化實際作了什麼，它的影響，而非作的內容。shell

這篇來自 Chris Beams 的優秀文章給咱們一個簡單的句子，能夠幫助咱們以祈使形式來書寫更好的 commit 信息：json

If applied, this commit will <commit message>
複製代碼

示例：後端

# 好示例
If applied, this commit will use InventoryBackendPool to retrieve inventory backend
複製代碼

# 壞示例
If applied, this commit will used InventoryBackendPool to retrieve inventory backend
複製代碼

首字母大寫

# 好示例
Add `use` method to Credit model
複製代碼

# 壞示例
add `use` method to Credit model
複製代碼

首字母須要大寫的緣由是遵照句子開頭使用大寫字母的語法規則。

這個實踐的使用可能因人而異，團隊間亦可能不一樣，甚至不一樣語言的人羣間也會不一樣。大寫與否，一個重要的點是要保持標準一致而且遵照它。

嘗試在沒必要查看源代碼的狀況下溝通變化內容

# 好示例
Add `use` method to Credit model

複製代碼

# 壞示例
Add `use` method
複製代碼

# 好示例
Increase left padding between textbox and layout frame
複製代碼

# 壞示例
Adjust css
複製代碼

不少場景中(例子：屢次提交、屢次變動和重構)這都有助於幫助代碼審查者理解代碼提交者當時的想法。

使用消息體來解釋『爲何』、『是什麼』、『怎麼作』以及附加細節信息

# 好示例
修復了 InventoryBackend 子類的方法名

InventoryBackend 派生出的類沒有
遵循基類接口

它之因此運行，是由於 cart 以錯誤的方式
調用了後端實現。
複製代碼

# 好示例
Cart 中對 credit 與 json 對象間作序列化和反序列化

基於兩個主要緣由將 Credit 實例轉化成 dict：

  - Pickle 依賴於類的文件路徑
  若是須要重構的話咱們不想破壞任何東西
  - Dict 和內建類型在默認狀況下是能夠經過 pickle 來序列化的
複製代碼

# 好示例
Add `use` method to Credit

從 namedtuple 變成 class
是由於咱們須要使用新的值來設置屬性（in_use_amount）
複製代碼

提交信息的主題和正文被一個空白行分割附加的空白行被認爲是提交信息正文的一部分。

相似 -，* 和 \ 的字符是用來提升可讀性的元素。

避免通用消息或者沒有任何上下文的消息

# 壞示例
Fix this

Fix stuff

It should work now

Change stuff

Adjust css
複製代碼

限制字符數量

推薦主題最多使用 50 個字符，消息體最多使用 72 個字符。

保持語言的一致性

對於項目全部者：選擇一個語言並使用該語言書寫全部的 commit 信息。理想狀況下，它應該匹配代碼註釋、默認翻譯區域（對於作了本地化的應用）等等。

對於項目貢獻者：基於已有 commit 歷史書寫一樣語言的 commit 信息。

# 好示例
ababab Add `use` method to Credit model
efefef Use InventoryBackendPool to retrieve inventory backend
bebebe Fix method name of InventoryBackend child classes
複製代碼

# 好示例（葡萄牙語示例）
ababab Adiciona o método `use` ao model Credit
efefef Usa o InventoryBackendPool para recuperar o backend de estoque
bebebe Corrige nome de método na classe InventoryBackend
複製代碼

# 壞示例（混合了英語和葡萄牙語）
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
efefef Add `use` method to Credit model
cdcdcd Agora vai
複製代碼

模板

這是一個樣板，由 Tim Pope 編寫，出如今文章高級 Git 手冊。

簡化變動內容到 50 字符左右或者更少

若有必要，可提供更詳細的說明文字。
將它包裝成大約 72 個字符左右。
在某些狀況下，第一行被視爲 commit 的信息主題，餘下文字被認爲信息正文。
將摘要和正文分離開的空白行頗有必要（除非你忽略了整個正文）；
不一樣的工具像 `log`、`shortlog`、`rebase`，
可能會變得混亂，若是你同時運行兩個。

解釋本次 commit 正在解決的問題。
專一於這次變動的緣由，而非如何變動（代碼會解釋這點）。
這次變動是否有反作用或其餘隱性後果？
這裏就是解釋它們的地方。

空白行以後有更進一步的段落。

 - 也能夠用要點符號。

 - 一般使用連字符或者星號做爲要點符號，
 前面有一個空格，中間有空白行，
 可是約定慣例各不相同。

若是你使用問題跟蹤，在底部放置它們的引用，
像下面這樣：

Resolves: #123
See also: #456, #789
複製代碼

Rebase 與 Merge

這節是 Atlassian 優秀教程中的一個 TL;DR，「Merge 與 Rebase」。

Rebase

TL;DR: 把你的分支中的 commit 一個接一個地應用到 base 分支，生成一個新樹。

Merge

TL;DR: 使用兩個分支間的差別，建立新的 commit，稱做（適當地）merge 提交。

爲何有些人更傾向於 merge 而不是 rebase？

我尤爲更傾向於 rebase 而不是 merge，理由包含：

它生成了一個『整潔的』提交歷史，沒有沒必要要的 merge commit。
所見即所得，舉例，在一次代碼審查中，全部的變動來自對應某種特殊化的標註的 commit，避免了來隱藏在 merge commit 中的變動。
更多的 merge 被提交者解決，而且每一個 merge 變化對應着具有合適信息的 commit。
- 對 merge 類 commit 作挖掘和審覈並不常見，所以避免這類操做能夠確保全部的變動都歸屬於某個 commit。

什麼時候作 squash？

「Squashing」是處理一系列 commit 並將它們壓縮爲一個 commit 的過程。

它在多種狀況下都有用，例子：

減小包含少許或者沒有上下文的 commit（錯誤修正、格式化、遺忘的內容）
將某些合併應用時更合理的獨立變動結合起來
重寫正在進行中這類 commit

什麼時候避免 rebase 和 squash？

避免在多人協做的公共 commit 或者共享分支中執行 rebase 和 squash。 rebase、squash 重寫歷史記錄、覆蓋已有 commit，在共享分支的 commit 中執行以上操做（例子，推送到遠程倉庫的 commit 或者來自其餘分支的 commit）可能形成混淆，而且因爲分歧的樹幹和衝突你們可能會丟失他們的變動（本地和遠程的）。

有用的 git 命令

rebase -i

使用它來壓制 commit，編輯信息，重寫/刪除/從新排序 commit，等等。

pick 002a7cc Improve description and update document title
pick 897f66d Add contributing section
pick e9549cf Add a section of Available languages
pick ec003aa Add "What is a commit" section" pick bbe5361 Add source referencing as a point of help wanted pick b71115e Add a section explaining the importance of commit messages pick 669bf2b Add "Good practices" section pick d8340d7 Add capitalization of first letter practice pick 925f42b Add a practice to encourage good descriptions pick be05171 Add a section showing good uses of message body pick d115bb8 Add generic messages and column limit sections pick 1693840 Add a section about language consistency pick 80c5f47 Add commit message template pick 8827962 Fix triple "m" typo pick 9b81c72 Add "Rebase vs Merge" section # Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands) # # Commands: # p, pick = use commit # r, reword = use commit, but edit the commit message # e, edit = use commit, but stop for amending # s, squash = use commit, but meld into the previous commit # f, fixup = like "squash", but discard this commit's log message # x, exec = run command (the rest of the line) using shell # d, drop = remove commit # # These lines can be re-ordered; they are executed from top to bottom. # # If you remove a line here THAT COMMIT WILL BE LOST. # # However, if you remove everything, the rebase will be aborted. # # Note that empty commits are commented out 複製代碼

fixup

使用它輕鬆地清理 commit 而且無須一個更復雜的 rebase 操做。這篇文章提供瞭如何以及什麼時候這麼作的很好的示例。

cherry-pick

它很是適用於在發佈到錯誤分支上的 commit，無須再次編碼。

示例：

$ git cherry-pick 790ab21
[master 094d820] Fix English grammar in Contributing
 Date: Sun Feb 25 23:14:23 2018 -0300
 1 file changed, 1 insertion(+), 1 deletion(-)
複製代碼

add/checkout/reset [--patch | -p]

假設咱們有如下差別：

diff --git a/README.md b/README.md
index 7b45277..6b1993c 100644
--- a/README.md
+++ b/README.md
@@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend
 ``
 # 壞示例（混合英語和葡萄牙語）
 ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
 cdcdcd Agora vai
 ``

+### 樣板
+
+這是一個樣板，[由 Tim Pope 編寫](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)，出如今文章 [**高級 Git 手冊**](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project)。
+
 ## 貢獻

 感謝任何形式的幫助，能夠幫到個人主題示例：
@@ -202,3 +205,4 @@ 感謝任何形式的幫助，能夠幫到個人主題示例：

 - [如何書寫 Git 的 Commit 信息](https://chris.beams.io/posts/git-commit/)
 - [高級 Git 手冊 —— Commit 指導](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
複製代碼

咱們可使用 git add -p 來只添加咱們須要的補丁，無須修改已經編寫的代碼。將較大的變動拆分紅小的 commit 或者重置/檢出特殊的變動。

暫存這個區塊 [y,n,q,a,d,/,j,J,g,s,e,?]? s
拆分紅 2 個區塊
複製代碼

區塊 1

@@ -186,7 +186,6 @@
 ``
 # 壞示例 (mixes English and Portuguese)
 ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
 cdcdcd Agora vai
 ``

暫存這個區塊 [y,n,q,a,d,/,j,J,g,e,?]？
複製代碼

區塊 2

@@ -190,6 +189,10 @@
 ``
 cdcdcd Agora vai
 ``

+### 樣板
+
+這是一個樣板，[由 Tim Pope 編寫](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)，出如今文章 [**高級 Git 手冊**](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project)。
+
 ## 貢獻

感謝任何形式的幫助，能夠幫到個人主題示例：
暫存這個區塊 [y,n,q,a,d,/,K,j,J,g,e,?]？
複製代碼

區塊 3

@@ -202,3 +205,4 @@ 感謝任何形式的幫助，能夠幫到個人主題示例：

 - [如何書寫 Git 的 Commit 信息](https://chris.beams.io/posts/git-commit/)
 - [高級 Git 手冊 —— Commit 指導](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [關於 Git 的 Commit 信息的注意事項](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
複製代碼