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