大神說：“Show me the code”，於是就有了程式碼評審。

“Talk is cheap。 Show me the code。”

——Linus Torvalds， founder of Linux and Git。

程式碼評審中同樣存在著“Talk is cheap。 Show me the code”，語言無力時，直接上程式碼吧。這就是我們今天要討論的話題——程式碼評審中的程式碼協同。

一 基於郵件列表的程式碼評審

這是一種和程式碼倉庫松耦合的程式碼評審模式，100%的程式碼都要經由一位或多位“仁慈的獨裁者”（benevolent dictator）程式碼評審後才能合併入程式碼倉庫。這種開發模式還需要開發者掌握一些命令列操作技巧以便完成程式碼在倉庫和郵件列表之間的轉換。採用這個模式的專案不多，不過 Linux、Git 開源社群就是按照這種模式運作的。

1 程式碼和郵件的相互轉換

程式碼轉換為電子郵件，要使用 git format-patch 命令。例如下面的命令將指定範圍的程式碼提交（例如在 origin/master 之後的新提交）轉換為電子郵件：

git format-patch origin/master。。HEAD

生成的補丁檔案的格式如下所示：

From： Author Nameauthor@emailSubject： ［PATCH］ first line of commit messagemore commit message。。。——-diff ——git 。。。content of patch

郵件頭中的 Subject： 欄位是郵件標題，使用 ［PATCH］ 作為標題字首，以提交說明的第一行作為標題內容。

更多的提交說明作為郵件內容，和郵件頭之間用一個空行分隔開。

用分隔符 ——- 作為提交說明的結束。

在分隔符 ——- 和 diff ——git 開始的補丁內容之間的文字被忽略。通常此處內容是提交的變更統計，開發者也可以在此處寫入不宜列入提交說明中的附加說明。

git format-patch 命令有很多引數，要結合不同場景使用，例如：

一個特性由多個提交構成，分散在多個提交中的提交說明難以描述整個特性，可以使用 ——cover-letter 引數，生成一封編號為 0000 的郵件，作為後續提交的摘要說明，便於評審者理解程式碼。

一個特性通常會多次迭代，就需要為每次迭代設定不同的版本。這就要用到 -v {num} 引數指定補丁的版本。版本將體現在郵件標題中，例如第二版本的補丁，郵件標題將使用 ［PATCH v2］ 作為字首。

回覆特定郵件，以便形成可追蹤的郵件線索，使用引數 ——in-reply-to=“{Message-ID}”，為電子郵件生成相關的 In-Reply-To： 和 References： 頭資訊。

預設提交本身的作者、提交說明的簽名區（trailer）提及的貢獻者會自動新增為郵件的收件人。要新增更多參與者，可以使用 ——to={email}、——cc={email} 引數。

將電子郵件轉換為程式碼，則使用命令 git am ［options。。。］ mail。。。 。該命令會將郵件正確轉換為 Git 倉庫中的提交。

使用 git send-email 命令，將包含程式碼提交的郵件傳送到郵件列表。

2 評審中的程式碼片段轉換為提交

程式碼評審以郵件回覆的方式完成。注意郵件回覆都要求用純文字格式，否則會被郵件伺服器退信。程式碼評審中發現小的文字錯誤，例如將 warning 寫成了 waring，評審者可能做出如下簡潔的回覆：

s/waring/warning/

這種約定俗成的格式大概是源於 sed 命令實現文字替換的語法。

評審者有時候會在回覆中貼上大段的程式碼補丁，為了使程式碼補丁和郵件上下文做出區分，會使用特殊的剪刀分隔符將郵件中的評論和程式碼補丁分隔開。

Subject： Re： whatever thread you‘re inSomebody else said：blah blah blahI disagree。 You should do it like this instead：——8 ——first line of commit messagemore commit message——-diff ——git 。。。

上面是 Peff（Jeff King）在郵件中給出的一個示範，看到其中的剪刀分隔符了麼？剪刀分隔符由多個減號（穿孔的分割線）和一個剪刀符號組成至少8個字元的分隔符。可選的分隔符有：—— 8—— 、——8 —— 、—— %—— 或 ——-% ——- 等。

使用 git am ——scissors 命令，能夠識別郵件中的剪刀分隔符，將郵件中的程式碼轉換為提交。

3 為提交貢獻者署名

Git的提交元資訊中只包含兩個署名資訊，一個是提交的原始作者（Author），一個是將提交合入倉庫或者對提交做了修補的提交者（Committer），而在提交評審過程中有過貢獻的人往往不只兩人，如何致敬貢獻者呢？Git 社群的實踐是在提交尾部（trailer）新增貢獻者簽名。貢獻者簽名由一個被動語態的關鍵字和貢獻者ID組成，例如：

Signed-off-by： UserEmail：通常由程式碼的貢獻者（Author）和程式碼合入時的提交者（Committer）提供的簽名。可由命令 git commit -s 、 git am -s 等命令自動新增。

Reported-by： UserEmail：問題的報告者。

Helped-by： UserEmail：對提交有過幫助的人。

Reviewed-by： UserEmail：評審者。

可以透過 Git 專案倉庫的提交歷史，看到更多的簽名示例。

4 使用 GitHub PR 實現程式碼到郵件的轉換

一個名為 GitGitGadget 工具藉助 GitHub 強大的擴充套件能力，透過向 gitgitgadget/git 倉庫傳送 pull request，實現提交到郵件的轉換，併發送到 Git 專案的郵件列表中。使用 GitGitGadget 參與 Git 社群程式碼貢獻詳見。

二 GitHub 程式碼評審中的協同

GitHub 使用 pull request 進行程式碼評審，評論中的程式碼塊兒也可以轉換為提交。

1 程式碼評論中嵌入程式碼塊

下圖中，點選評論工具欄第一個按鈕，可以在評論中嵌入程式碼塊：

2 評論中程式碼塊轉換為提交

對 pull request 的源倉庫具有寫許可權的使用者，可以將評審中的程式碼庫轉換為提交，如下圖所示：

於是程式碼評審中會增加一個新的修正提交。GitHub 的這個功能對於程式碼評審中發現的一些小問題，還是非常方便的。但是大的修改就無能為力了。

3 線下評審

對於功能複雜的 pull request，在線上瀏覽程式碼不方便，也不能線上除錯程式碼，這時線下獲取並瀏覽程式碼，就非常有必要了。

GitHub 的程式碼倉庫中為每一個程式碼評審設定了特殊的關聯引用：

refs/pull/{ID}/head ：關聯 pull request 的源提交。

refs/pull/{ID}/merge ：對於沒有衝突的 pull request，這個引用指向一個成功的合併提交。

程式碼評審者使用如下命令可以獲取 pull request （例如編號為 123 的 PR）指向的提交：

git fetch origin refs/pull/123/headgit switch -d FETCH_HEAD

評審者可以線下除錯 pull request 指向的程式碼，但是對程式碼做出的本地修改，沒有辦法直接更新到線上的程式碼評審中。

阿里巴巴的雲效Codeup，支援線下到線上的程式碼協同。

三 雲效Codeup程式碼評審中的協同

無論是 GitHub 還是 Gitlab，開發者建立程式碼評審首先需要將程式碼推送到線上獨立的分支中（無論是在線上的派生倉庫，還是目標倉庫），然後再透過網頁選擇來源倉庫、分支及目標倉庫、分支，建立程式碼評審。

GitHub 和 Gitlab 這種程式碼評審方式，或者要引入冗餘的派生倉庫，或者需要為開發者賦予在倉庫中的寫入許可權，並容易引發雜亂的分支管理。

1 適合主幹開發的無分支建立程式碼評審

雲效 Codeup 可以透過 git push 命令在客戶端直接建立程式碼評審，無需建立派生倉庫或者在倉庫中建立特性分支。例如在客戶端執行如下命令：

git push origin HEAD：refs/for/master/topic1

該命令會在服務端建立新的程式碼評審，或者如果已經存在相同使用者、相同命令建立的程式碼評審則會更新評審中的提交。建議安裝我們開源的 git-repo 工具，則可以用更簡單的命令列，實現從客戶端建立/更新程式碼評審。

git pr

2 線下評審，線上協同

和 GitHub 類似，雲效 Codeup 建立的程式碼評審都有一個特殊引用相關聯，格式為：refs/merge-requests/{ID}/head。程式碼評審者可以使用 git fetch 命令獲取特定的程式碼評審（以編號123為例）指向的程式碼，進行線下程式碼評審。

git fetch origin refs/merge-requests/123/headgit switch -d FETCH_HEAD

如果安裝了 git-repo，可以使用下面更為簡潔的命令：

git download 123

程式碼評審者除了可以在本地倉庫中瀏覽、除錯程式碼，還可以更新程式碼、建立提交，然後將本地新增提交更新到線上的程式碼評審中。命令示例如下：

git pr -c 123

在雲效 Codeup，開發者和評審者可以基於程式碼評審進行更為流暢的程式碼協同。3 Git proc-receive 掛鉤

上述“線下評審、線上協同”功能的核心是 Git 的 proc-receive 掛鉤和 report-status-v2 新能力。這一功能由阿里巴巴貢獻給 Git 社群，並在 Git 2。29。0 釋出。