第一次把Git、Repo、Gerrit三樣工具組合到同一條工作流里是因為一個很現(xiàn)實的問題一個移動系統(tǒng)源碼工程幾十個獨立模塊倉庫鋪開十幾個團隊并行開發(fā)單靠Git倉庫加中心服務(wù)器已經(jīng)完全管不過來了。分支沖突每天發(fā)生權(quán)限又粗想給某個模塊設(shè)置“需要評審才能合入”的規(guī)則在純Git上做起來非常別扭。最后我們引入了Repo來統(tǒng)一管理多倉庫清單用Gerrit作為評審門禁形成了一條“本地Commit→推送評審→評審通過→自動合入”的鏈路。這篇文章不是官方文檔的復述而是我在這條鏈路里從部署到日常使用踩過的坑和沉淀下來的經(jīng)驗適合正在評估是否要上這套組合、或者已經(jīng)在用但經(jīng)常被Change-Id和refs/for搞暈的團隊參考。1. 為什么單Git倉庫撐不住非要Repo和Gerrit一起上經(jīng)常有人問我“我們Git用得挺好的干嘛還要加Repo和Gerrit”我的回答一般都很簡單——規(guī)模和協(xié)作方式變了。1.1 單倉庫在大規(guī)模并行下為什么先崩潰單Git倉庫在小團隊里玩得很順三五個人各自拉分支改完合并沖突量小處理起來也快?？梢坏﹤}庫數(shù)量上到幾十個、團隊擴到十幾個三個問題會立刻浮出水面。第一分支與合入的沖突無法收斂。幾十個模塊并行時每次merge都要處理一堆非功能性沖突比如自動生成文件的變動、目錄結(jié)構(gòu)調(diào)整、格式化差異。這些沖突跟業(yè)務(wù)邏輯毫無關(guān)系卻要消耗大量工程師時間而且A團隊改了公共接口B團隊半夜合入才發(fā)現(xiàn)編譯不過的情況特別多。第二權(quán)限粒度太粗。Git原生對倉庫的權(quán)限控制主要集中在“能否推送”它很難表達“誰可以創(chuàng)建分支、誰可以推送到主干分支、誰必須經(jīng)過評審才能合入”。一旦開發(fā)人員變多很容易出現(xiàn)有人繞過評審直接push到受保護分支的事故事后你想查是誰合入的、誰批準的都無從下手。第三審計和追溯能力弱。代碼評審中產(chǎn)生的討論、誰給了2、誰觸發(fā)了合入——這些信息在純Git日志里基本是缺失的。項目復盤時想還原一個改動的完整決策過程只能靠聊天記錄這顯然不合理。1.2 Repo補上的“多倉庫清單”短板Repo解決的問題很粗暴但很有效它給多倉庫工程加了一個“清單層”。這個清單通常是一個獨立的manifest倉庫里面用XML文件記錄著所有子倉庫的遠程地址、默認分支、固定版本。每個開發(fā)者只要拉到同一份manifest再執(zhí)行一次repo sync本地的幾十個倉庫就能整整齊齊地恢復到同一狀態(tài)。沒有Repo的時候你新加入一個項目得手動一個一個git clone還很容易從不同的遠程分支拉到不一致的代碼版本有了Repo之后“可復現(xiàn)”從口號變成了默認能力。Repo還提供了跨倉庫操作的口子。比如repo start可以一次性為所有倉庫創(chuàng)建同名分支repo status可以一眼看到幾十個倉庫的整體改動情況repo grep可以在跨倉庫代碼里搜索關(guān)鍵字。這些能力本身不復雜但在多倉庫場景下能把日常操作的效率提升一個量級。1.3 Gerrit填上的“評審與門禁”缺口Gerrit本質(zhì)上是一個代碼托管加評審服務(wù)器但它最關(guān)鍵的貢獻是把“合入”這件事變成了可以被評審、被記錄、被阻止的受控事件。開發(fā)者默認不能直接把commit推到refs/heads/xxx只能推到refs/for/xxx。Gerrit收到后不會立刻更新目標分支而是生成一個待評審的Change。評審人在界面上打分、留評論全部通過后合入動作才由Gerrit服務(wù)端真正執(zhí)行。這個設(shè)計把“修改代碼”和“進入主干”徹底分離權(quán)限控制、流程審計、質(zhì)量門禁全都有了落點。1.4 什么項目適合什么項目別生搬硬套項目類型是否適合這套組合原因幾十個倉庫、多團隊并行的工程非常適合清單統(tǒng)一管理有收益評審門禁能擋事故3到5人的單倉庫小團隊不適合引入Repo和Gerrit的運維成本超過收益需要大量外部臨時貢獻者的項目視情況而定評審有價值但Gerrit門檻可能嚇跑新手純個人項目完全不適合一個Git遠端備份足夠我見過有團隊只有六個倉庫也要硬上Gerrit每天被Change-Id和權(quán)限配置折騰得苦不堪言最后一怒之下退回GitLab。工具組合沒有絕對的好壞只有合不合適的場景。2. 把Repo同步鏈跑通init、sync與manifest的配合確定要上這套組合之后第一步就是把這根同步鏈跑通。這一步看著簡單但版本兼容、manifest寫法、本地分支策略都是容易出問題的地方。2.1 基礎(chǔ)工具Git版本、Repo腳本與Python兼容性建議把Git升級到較新的穩(wěn)定版老版本Git在處理淺克隆、安全策略和部分子命令時行為差異很大出問題后很難排查。Repo本身是一個Python腳本早期版本依賴Python 2現(xiàn)在主流版本都要求Python 3安裝時最好直接用發(fā)行版?zhèn)}庫里帶的repo或者從官方渠道拉取并校驗版本。一個常見的坑直接用apt install repo裝上的版本可能偏舊和某些Gerrit服務(wù)端的協(xié)議不兼容表現(xiàn)就是同步時報奇怪的SSL錯誤或者解析XML失敗。遇到這種情況優(yōu)先升級repo腳本版本而不是去折騰服務(wù)端。2.2 manifest倉庫設(shè)計remote、default與project的意義manifest倉庫是整個多倉庫工程的“總藍圖”理解它比背命令重要得多。下面是一個典型的manifest文件結(jié)構(gòu)manifest remote nameorigin fetchssh://git.example.com/ reviewhttps://gerrit.example.com// default revisionmain remoteorigin/ project pathapp/core namemodules/core / project pathapp/network namemodules/network revisiondev-1.2 / /manifestremote標簽里的fetch是所有子倉庫URL的前綴review字段是Gerrit地址供repo upload生成評審目標。default標簽里的revision是默認分支所有沒單獨寫revision的project都會用這個分支。某個模塊需要緊跟特定分支時就在project標簽里單獨覆蓋像上面的modules/network一樣鎖定在dev-1.2。我個人的建議是manifest里盡量鎖定固定revision至少對關(guān)鍵模塊使用tag或SHA而不是裸的分支名。分支名跟著遠端走今天同步的是這個狀態(tài)明天可能就是另一個狀態(tài)出了問題很難復現(xiàn)。2.3 首次走通repo init與sync初始化一組倉庫命令很簡潔但每一步都有事情在發(fā)生repo init -u ssh://git.example.com:29418/manifest.git -b main repo sync -j8 -crepo init會在當前目錄生成一個.repo目錄里面存放manifest倉庫本體、各項目的引用信息和鉤子配置。repo sync的任務(wù)是把manifest里記錄的每個項目同步到本地-j8是8個任務(wù)并行拉取-c是只同步當前分支而不是所有遠端分支能省不少時間。首次同步的體驗跟網(wǎng)絡(luò)環(huán)境關(guān)系很大如果之前有人同步過同樣的工程可以配置本地鏡像或者緩存目錄repo init -u manifest地址 --reference/path/to/mirror這能把后續(xù)同步的耗時壓縮到分鐘級。沒有鏡像的情況下幾十個倉庫逐一clone確實會等很久這是多倉庫工作的常態(tài)耐心點就好。2.4 用repo start建立特性分支同步完成后不要直接在默認分支上改代碼而是用repo start為所有倉庫創(chuàng)建本地主題分支repo start stable-1.0 --all這條命令的含義是在每一個倉庫里基于當前manifest指定的版本創(chuàng)建一個名為stable-1.0的本地分支并讓它追蹤對應(yīng)的遠端分支。這樣做的好處是后續(xù)你在任何一個倉庫里的提交都發(fā)生在自己的命名空間里不會跟某個版本的快照糾纏在一起。改完代碼后Git分支名、Gerrit上顯示的目標分支關(guān)系一目了然。3. 從commit到評審合入的完整閉環(huán)同步鏈跑通之后日常工作的核心就是“本地提交→推送評審→通過合入”這個閉環(huán)。很多新人在這個階段被Change-Id和refs/for繞得暈頭轉(zhuǎn)向我拆細一點說。3.1 Change-IdGerrit識別同一筆改動的身份證Git里每次commit有一個唯一的哈希值但這個哈希在--amend、rebase之后會變化。如果Gerrit靠commit哈希來識別評審任務(wù)那么同一筆邏輯改動連續(xù)修改兩次就會在系統(tǒng)里變成兩個互不相關(guān)的Change評審歷史和討論全部斷裂。所以Gerrit定義了Change-Id以字母I開頭后面跟40位十六進制字符的一行字符串放在commit message末尾。無論commit哈希怎么變只要Change-Id還在Gerrit就把多次推送歸入同一個Change并生成不同的Patch Set。評審人在新Patch Set上繼續(xù)追評上下文不斷。3.2 commit-msg hook的安裝與驗證Change-Id通常不是人工手寫的而是由Git的commit-msg鉤子在每次提交時自動追加。Gerrit服務(wù)端提供了這個hook開發(fā)者需要把它安裝到倉庫的.git/hooks/目錄里。安裝命令一般是這樣的gitdir$(git rev-parse --git-dir) curl -o $gitdir/hooks/commit-msg https://gerrit.example.com/tools/hooks/commit-msg chmod x $gitdir/hooks/commit-msg也可以用scp的方式拉取scp -p -P 29418 usernamegerrit.example.com:hooks/commit-msg .git/hooks/安裝后驗證一下ls -l .git/hooks/commit-msg只要這個文件存在且有執(zhí)行權(quán)限之后每次git commithook都會在提交信息自動追加一行Change-Id。3.3 推送到refs/for而不是refs/heads評審流的推送命令是git push origin HEAD:refs/for/main這里的refs/for/main是Gerrit的特殊命名空間推到這里的commit不會直接更新main分支而是生成一個待評審的Change。真正更新main分支的動作由Gerrit在評審通過后執(zhí)行。新人最容易犯的錯是直接執(zhí)行g(shù)it push origin HEAD:refs/heads/main這在多數(shù)團隊里會被權(quán)限系統(tǒng)直接拒絕因為refs/heads/*通常只開放給維護者。如果權(quán)限配置不當沒有攔住那就是繞過評審直接改主干屬于流程事故。所以團隊里一定要做保護性配置**普通開發(fā)者只有refs/for/的推送權(quán)限r(nóng)efs/heads/只留給機器用戶或特定維護組。3.4 評審、打分、合入生命周期一個Change的完整旅程大致如下開發(fā)者推送refs/for/mainGerrit生成新Change。在Gerrit頁面上添加Reviewer評審人逐行看代碼、留評論。代碼質(zhì)量通過后有權(quán)限的人給Code-Review 2。CI或驗證人員跑完測試后給Verified 1。兩個條件都滿足后點Submit合入。如果合入時發(fā)現(xiàn)目標分支已經(jīng)領(lǐng)先Gerrit會提示Need Rebase。這時需要在本地把目標分支最新代碼拉下來rebase自己的提交再重新推送。Gerrit會在同一個Change下生成新的Patch Set評審記錄保持連續(xù)。4. 部署Gerrit側(cè)的準備賬號、權(quán)限與合入策略很多團隊在客戶端這邊折騰了半天服務(wù)端配置卻是隨手搞的導致后面流程各種別扭。Gerrit服務(wù)端的幾個關(guān)鍵點值得好好設(shè)計。4.1 SSH別名與Gerrit賬號打通開發(fā)者連Gerrit一般走SSH端口默認是29418。為了方便我會在每個人的~/.ssh/config里加一段Host gerrit HostName gerrit.example.com Port 29418 User username這樣后面所有帶gerrit主機名的操作都會自動用配置的端口和用戶名。第一次連接時Gerrit會提示你把SSH公鑰上傳到賬號里驗證一下ssh -p 29418 usernamegerrit.example.com能返回類似**** ****的歡迎信息賬號就通了。4.2 權(quán)限組與Label的設(shè)計Gerrit的權(quán)限模型有一個核心概念權(quán)限繼承。根項目All-Projects定義了全局權(quán)限所有項目可以從它繼承子項目可以覆蓋或追加。這樣團隊只需要維護一套基線規(guī)則不用每個倉庫單獨配置。我常用的配置基線是refs/for/*允許所有注冊開發(fā)者Push。refs/heads/*默認拒絕Push僅通過評審Submit合入。Label Code-Review2權(quán)限只授予主程和維護者組成的組。Label Verified1權(quán)限通常授予CI機器人。這一套配下來就能保證“誰都能提代碼但只有被授權(quán)的評審人能放行”。4.3 三種合入策略怎么選Gerrit支持好幾種Submit策略影響的是合入后目標分支的歷史形態(tài)。我把它們放在一起對比策略歷史形態(tài)適用場景Merge If Necessary保留真實合并記錄存在merge節(jié)點并行分支多、不希望頻繁rebaseFast Forward Only線性歷史沒有merge節(jié)點追求簡潔歷史允許本地rebaseCherry Pick提交被重放到最新主干嚴格單線開發(fā)版本管理要非常干凈我自己更偏好Fast Forward Only歷史干凈回滾定位容易代價是每個開發(fā)者在推送前需要把目標分支最新代碼rebase到本地。如果團隊實在不愿意頻繁處理rebase沖突再退回Merge If Necessary。4.4 讓CI去當Verified很多團隊的Verified是負責人手動點的這很不科學。正確做法是接入CI流水線每次Change更新時Gerrit觸發(fā)一次構(gòu)建CI跑完把結(jié)果打回Verified 1或Verified -1。沒有Verified通過的Change不允許合入這樣合入質(zhì)量從人肉保證變成了自動化保證。5. 高頻故障的完整排查鏈路工具鏈用得越久踩坑越多但這些坑大多是同一類問題反復出現(xiàn)。我把實戰(zhàn)中最高頻的四個故障和處理過程完整寫出來照著排查能省很多時間。5.1 缺Change-Id被拒從現(xiàn)象到根因現(xiàn)象推送時出現(xiàn)類似下面的報錯! [remote rejected] HEAD - refs/for/main (missing Change-Id in commit message)這是Gerrit收到commit后發(fā)現(xiàn)沒有Change-Id直接拒絕接收。完整的排查鏈路如下先確認本機是否安裝了commit-msg hookls -l .git/hooks/commit-msg如果文件不存在安裝它。如果文件存在但沒執(zhí)行權(quán)限chmod x .git/hooks/commit-msg。查看本地提交信息是否已經(jīng)有Change-Idgit log -1 --format%B確認缺失時對最近一條提交執(zhí)行g(shù)it commit --amend讓hook重新生成Change-Id并追加到message里。再次推送。這里有一個細節(jié)如果commit message里出現(xiàn)了兩行Change-IdGerrit會懵因為它不知道該以哪個為準。所以amend后要檢查message保留一行就好。5.2 repo sync撞上本地未提交改動現(xiàn)象執(zhí)行repo sync時報錯error: path/to/repo/: uncommitted changes are presentRepo為了不破壞本地工作遇到未提交改動會直接中斷同步。排查和處理的正確順序是先進入報錯倉庫查看具體改動cd path/to/repo git status如果這些改動是你要保留的先暫存起來git stash回到工程根目錄重新同步repo sync同步完成后再恢復暫存內(nèi)容git stash pop有一個需要提醒的點不要一上來就加-f強制同步。-f只是跳過出問題的倉庫繼續(xù)同步其他倉庫那個倉庫的本地改動并不會被處理最終容易形成“你以為同步了其實某個倉庫還在舊狀態(tài)”的假象。5.3 提交進錯了目標分支現(xiàn)象本想在release-1.2分支上開發(fā)推送時手滑點成了refs/for/mainGerrit上生成一個目標分支錯誤的Change。排查步驟看當前本地HEAD在哪個分支git log --oneline -3 git branch -vv確認最近的commit是不是指向了錯誤方向。處理方式分兩種情況如果commit還沒推送到Gerrit直接軟回退git reset --soft HEAD~1然后切到正確分支重新提交。如果已經(jīng)推到了Gerrit成了Change在Gerrit頁面上先給這個錯誤Change點Abandon本地把commit遷移到正確的目標分支再重新推送到對應(yīng)的refs/for/xxx。預防方法是每次推送前用dry-run看一眼目標git push --dry-run origin HEAD:refs/for/release-1.2這條命令會打印出將要推送的內(nèi)容和目標不會真的提交花一秒鐘能擋住大部分手滑。5.4 rebase后Change-Id丟失的補救現(xiàn)象本地rebase或者處理沖突時commit message被重寫Change-Id行丟了再次推送時又報missing Change-Id。處理思路是讓Change-Id回到message里并保持和Gerrit上原Change一致。git commit --amend在打開的編輯器里把原來的Change-Id行重新粘貼回去保存退出再推送。如果連原來的Change-Id都不記得了可以到Gerrit頁面上找到原Change里面每一行都能看到Change-Id。我習慣在重新rebase之后批量檢查所有提交里是否都還有Change-Idgit log --format%H %s %b | grep -c Change-Id:跟預期提交數(shù)量對得上才push對不上就先處理。6. 長期協(xié)作下來真正有價值的心法工具層面的坑都聊完了最后說幾個跟流程設(shè)計和團隊習慣有關(guān)的心法。這些是讓整套組合真正發(fā)揮價值的軟性因素。6.1 一個Change只干一件事評審人最反感的是一個大Change里既改了接口又修了bug還順手改了格式。Gerrit的評審界面是按文件逐行展示的多件事情混在一起評審人很難判斷每一處改動是不是合理。堅持一個Change只解決一個問題評審速度會快很多出問題回溯時也清晰。6.2 Topic把跨倉庫改動綁在一起多倉庫場景下一個功能經(jīng)常要同時改好幾個倉庫。Gerrit支持給Change設(shè)置Topic同名Topic的多個Change可以一起展示、一起評審、一起合入還能在頁面上看到它們之間的依賴關(guān)系。這比在備注里寫“配合xxx分支的xxx提交”靠譜得多。6.3 讓驗證變成自動化的聲音人工點Verified這件事又慢又不可靠人在疲勞時根本不記得點。把CI接入Verified之后合入門禁有了客觀標準開發(fā)者也更愿意在推送前自己先跑一遍靜態(tài)檢查和單測因為CI沒過推上去也是白推。6.4 定期修剪僵尸Change與本地分支Gerrit上有大量長期不更新的Change會慢慢變成“僵尸”。我每個迭代結(jié)束會花半小時清理確認已經(jīng)合入的Change不必處理但長期沒動靜且功能已經(jīng)放棄的果斷Abandon。本地倉庫里那些repo start開出來的舊特性分支合入后盡快刪掉否則幾十個倉庫的本地分支列表會膨脹到?jīng)]法看。6.5 代碼評審里最有用的溝通習慣最后一點經(jīng)驗跟技術(shù)無關(guān)但非常影響效率評審意見里多寫“為什么”少寫“怎么改”。比如“這里應(yīng)該用事務(wù)包裹因為兩步操作需要原子性”比“這里加個Transactional”有用得多。前者教的是設(shè)計原則后者只是給了個補丁。評論區(qū)一旦變成“按我說的改”的戰(zhàn)場代碼質(zhì)量反而會下降?；氐健癎it-Repo-Gerrit”這套組合本身。有人抱怨它門檻高但一旦團隊過了磨合期它會變成一種“默認有人兜底”的安全感。合入門禁防的是手滑清單統(tǒng)一防的是沉默的版本漂移Change-Id防的是補丁在評審中丟失脈絡(luò)。我們從一開始覺得多了一道工序到后來完全離不開中間靠的就是反復踩坑和把這些約定變成肌肉記憶。如果你們團隊也在考慮這套組合希望這篇文章能幫你把第一天到第一百天的路都鋪平一點。