1. 项目概述Gerrit与Repo的协同工作流如果你在从事基于AOSPAndroid Open Source Project或类似大型开源项目的开发或者所在公司的代码管理规模已经达到了“仓库森林”的程度那么你大概率已经接触过Gerrit和Repo这两个名字。它们常常被并列提及但各自扮演的角色却截然不同。简单来说Repo是那个帮你管理成百上千个Git仓库的“大管家”而Gerrit则是那个负责审查每一笔代码变更的“守门人”。单独使用任何一个在大规模协作开发中都会感到掣肘但将它们组合起来就形成了一套非常经典且高效的代码协作与集成流水线。我经历过从混乱的Git分支管理到引入这套工具的完整过程也踩过不少坑。很多新手会觉得这套组合学习曲线陡峭配置复杂但一旦跑通团队协作的效率和代码质量的控制能力会有质的飞跃。这篇文章我就以一个过来人的身份拆解Gerrit和Repo的核心概念、协同工作原理并分享从环境搭建到日常提交、审查、集成的全流程实操细节以及那些官方文档里不会写的“血泪教训”。2. 核心工具拆解Repo与Gerrit各司其职在深入使用之前必须彻底理解这两个工具的设计哲学和职责边界。混淆它们的概念是后续一切混乱的根源。2.1 Repo多仓库的秩序管理者Repo并不是一个版本控制系统它本身是一个用Python编写的脚本。它的核心价值在于解决“项目代码由数十个甚至数百个独立的Git仓库组成”所带来的管理噩梦。想象一下你要为Android系统贡献一个涉及框架层、系统服务、设置应用等多个模块的改动手动去每个仓库拉取、切换分支、提交、推送其繁琐程度和出错概率是无法接受的。Repo通过一个名为manifest.xml清单文件的配置文件来定义整个代码项目的结构。这个文件通常托管在一个独立的Git仓库中我们称之为manifest仓库。这个文件里写明了所有子项目的Git仓库地址。每个子项目的检出路径在本地工作目录中的位置。每个子项目的默认分支和修订版本可以是分支名也可以是具体的commit hash。当你执行repo init -u manifest仓库地址时Repo会克隆这个清单仓库并根据其中的定义自动化地为你克隆或同步所有指定的子项目仓库到正确的路径下并切换到指定的修订版本。之后你可以使用repo sync一条命令同步所有仓库到清单文件定义的最新状态用repo start 分支名 .在所有仓库或指定仓库上创建并切换到一个统一的功能分支。关键理解Repo让你的视角从“管理几百个Git仓库”提升到“管理一个由清单文件定义的超级项目”。你大部分时间是在和这个“超级项目”打交道Repo工具帮你把命令分发到各个子仓库去执行。2.2 Gerrit基于Git的代码评审门户Gerrit是一个基于Web的代码评审工具它本身也是一个Git服务器。与GitLab、GitHub内置的Pull Request/Merge Request机制不同Gerrit采用了一种更“重量级”的评审模型。它的核心工作流程围绕“Change”这个概念展开。你不是简单地把代码推送到远程分支然后创建合并请求。在Gerrit的工作流中你向一个特殊的引用refs/for/branch-name推送你的提交。这个动作并不会直接更新分支而是在Gerrit服务器上创建了一个待评审的“变更集”Change。这个变更集拥有独立的URL评审者可以在上面进行行级评论、打分Code-Review 1, 2, -1等、并执行测试验证。只有当一个变更集获得了足够的正面评分通常是Code-Review 2 和 Verified 1并且没有冲突时项目维护者或具备相应权限的人才能将其“提交”Submit。提交动作会将这个变更合并到目标分支如refs/heads/master并自动将变更标记为已合并。关键理解Gerrit将“代码推送”和“代码合入”两个动作解耦并在中间插入了强制的、结构化的评审环节。它维护了目标分支的线性与洁净因为所有合入都必须通过Change避免了直接向分支推送可能带来的混乱。2.3 协同模式Repo Gerrit 如何联动理解了各自角色它们的协作模式就清晰了初始化与同步开发者使用repo init和repo sync从公司的Gerrit服务器或镜像拉取由清单文件定义的完整代码树。开发与提交在本地修改后使用repo upload命令。这个命令非常智能它会自动识别你修改了哪些子项目。在每个被修改的子项目中将你的提交推送到Gerrit服务器对应的refs/for/target-branch。为所有推送的提交在Gerrit上创建关联的Change一个跨仓库的修改可能会创建多个Change但它们可以通过topic关联。评审与迭代评审者在Gerrit网页端进行评论。开发者根据反馈在本地修改后可以使用git commit --amend修改原提交保持Change ID不变然后再次repo upload。Gerrit会识别出这是同一个Change的新补丁集Patch Set自动更新原评审任务历史评论可以保留。合入与同步Change被批准并提交Submit后其代码就进入了官方分支。其他开发者通过repo sync即可将这部分更新拉取到本地保持代码同步。这套流程强制了代码在进入主分支前必须经过评审并且通过Repo管理了跨仓库变更的一致性非常适合需要高度协同和高质量控制的大型项目。3. 环境准备与初始配置实战理论讲完我们进入实战。假设你新加入一个使用这套流程的团队以下是你的上手步骤。3.1 安装Repo客户端Repo是一个客户端工具首先需要把它下载到你的系统路径里。通常的做法是# 创建一个存放Repo的目录并加入PATH mkdir -p ~/.bin export PATH~/.bin:$PATH # 下载Repo启动器 curl https://storage.googleapis.com/git-repo-downloads/repo ~/.bin/repo # 如果遇到网络问题可以使用国内镜像例如 # curl -s https://mirrors.tuna.tsinghua.edu.cn/git/git-repo -o ~/.bin/repo # 赋予执行权限 chmod ax ~/.bin/repo将export PATH~/.bin:$PATH这行添加到你的~/.bashrc或~/.zshrc中以便永久生效。实操心得Repo的版本最好与服务器端即manifest仓库所期望的保持一致。有些项目的manifest.xml会通过repo-rev属性指定需要的Repo版本。如果遇到奇怪的问题可以尝试用repo init -u ... --repo-url[特定的repo仓库地址] --repo-branch[分支]来指定Repo工具本身的版本。3.2 配置Git与Gerrit身份Gerrit服务器通常使用HTTP/HTTPS协议并通过你的账户密码或HTTP凭据助手进行认证。此外Gerrit依赖提交者信息中的邮箱地址来关联账号。# 配置全局用户信息请替换成你的信息 git config --global user.name Your Name git config --global user.email your.emailcompany.com # 配置HTTP认证缓存避免每次push都输密码 git config --global credential.helper store # 或者使用内存缓存更安全 # git config --global credential.helper cache # git config --global credential.helper cache --timeout3600首次向Gerrit推送时会提示输入用户名和密码可能是你的LDAP账号或Gerrit注册账号。使用store模式会明文保存在~/.git-credentials文件中请确保你的系统安全。cache模式将凭据存放在内存中一段时间。3.3 初始化工作目录并同步代码这是与项目代码的第一次接触。# 创建一个工作目录 mkdir my-project cd my-project # 初始化Repo指向manifest仓库 repo init -u https://gerrit.company.com/platform/manifest -b master # -u: manifest仓库的URL # -b: 指定manifest仓库本身的分支通常为master # 同步所有代码到本地。这是一个漫长的过程取决于项目大小。 repo sync -c -j8 # -c: 只同步manifest中指定的分支当前分支节省流量和时间。 # -j8: 使用8个线程并行下载数字可根据网络和机器性能调整。执行repo sync后你的当前目录下就会按照manifest.xml的布局出现所有子项目的文件夹每个都是一个独立的Git仓库。踩坑记录网络中断是repo sync最大的敌人。如果中途失败可以多次执行repo sync它会自动续传。但如果遇到某个仓库死活同步不下来可以尝试repo sync project-path单独同步这个仓库。有时也需要检查本地磁盘空间是否充足。3.4 获取并安装Change-Id钩子这是Gerrit工作流的关键一环。Gerrit要求每个提交都必须包含一个唯一的Change-Id标签在提交信息中。这个标签用于将同一个修改的不同补丁集Patch Set关联起来。Repo可以帮你自动安装这个钩子脚本# 进入任意一个Repo管理的子项目目录或者在工作目录根目录执行 cd .repo/manifests # 或者在工作目录根目录执行 curl -Lo git rev-parse --git-dir/hooks/commit-msg https://gerrit.company.com/tools/hooks/commit-msg chmod x git rev-parse --git-dir/hooks/commit-msg更通用的方法是这个钩子脚本通常可以从你的Gerrit服务器首页的“Documentation” - “Download” 部分找到。安装后每次你执行git commit或git commit --amend这个钩子会自动在提交信息的最后一行添加或更新一个Change-Id: Ixxxxxx行。验证钩子是否生效cd path/to/any/project git commit --allow-empty -m “Test commit-msg hook” git log -1你应该能在最新的提交信息底部看到一行Change-Id: I40a6d...。核心技巧务必在第一次提交前确保所有仓库都安装了这个钩子。你可以写一个小脚本遍历所有Repo管理的仓库进行安装。否则缺少Change-Id的提交将无法通过repo upload推送到Gerrit。4. 日常开发工作流全解析环境配好钩子装上现在可以开始真正的开发了。我们以一个需要修改两个模块Project A和Project B的功能为例。4.1 创建功能分支永远不要在本地的主分支如master上直接修改。使用Repo为所有相关仓库创建统一的功能分支。# 在工作目录根目录为所有仓库创建分支 “feature-xyz” repo start feature-xyz --all # 或者如果你确定只修改某几个项目可以指定项目路径 repo start feature-xyz platform/framework/base platform/packages/apps/Settings这个命令会在每个指定的仓库中基于当前清单文件锁定的修订版本即上次repo sync后的状态创建并切换到一个名为feature-xyz的分支。这保证了你的修改有一个清晰的、统一的起点。4.2 进行代码修改与提交进入具体的子项目目录进行修改和普通的Git操作无异。cd platform/framework/base # ... 进行你的代码编辑 ... git add . git commit -m “Fix null pointer issue in ServiceManager This patch checks the binder object before using it to avoid potential NPE when service is not ready. Bug: PROJ-1234 Change-Id: I这里会自动生成”注意提交信息格式首行简短摘要空一行然后是详细描述。Bug:标签是很多项目要求的用于关联问题追踪系统。最后的Change-Id由钩子自动添加不要手动修改或删除它。对另一个模块也进行类似操作。cd ../../packages/apps/Settings # ... 修改 ... git add . git commit -m “Update UI to reflect service status Add a status indicator in the settings page. Bug: PROJ-1234 Change-Id: I另一个自动生成的ID”4.3 上传变更到Gerrit进行评审这是将本地提交转化为Gerrit上待评审Change的关键一步。# 在工作目录根目录执行 repo upload执行后Repo会扫描所有项目找出你有本地提交但尚未推送的分支。为每个有提交的项目列出将要上传的提交并让你确认。将这些提交推送到Gerrit服务器上对应远程仓库的refs/for/master假设目标分支是master。在Gerrit上为每个推送创建新的Change或者如果Change-Id已存在则创建新的补丁集Patch Set。在上传过程中Repo会提示你输入评审者Reviewer的邮箱地址。你也可以直接按回车跳过后续在Gerrit网页端添加。高级用法使用repo upload --cbr可以在上传前自动基于远程目标分支进行变基rebase确保你的提交是基于最新的代码减少冲突。我强烈建议养成这个习惯。4.4 处理评审意见与更新补丁集评审者在Gerrit网页端对你的Change提出了意见。你需要修改代码。# 进入需要修改的项目目录 cd platform/framework/base # 修改代码... git add . # 使用 --amend 修改上一次提交这能保持Change-Id不变 git commit --amend # 保存提交信息可以更新描述保存后钩子会自动更新Change-Id行但ID值不变 # 再次上传 repo upload这次因为Change-Id相同Gerrit会识别出这是针对已有Change的新补丁集例如从Patch Set 1更新到Patch Set 2而不会创建新的Change。所有之前的评论会被保留但可以标记为“已修复”。4.5 合入变更与同步最新代码当你的Change获得了足够的2评分并通过验证后具备提交权限的人可能是你也可能是项目维护者点击“SUBMIT”按钮。代码就正式合入了目标分支。之后你和其他所有开发者都需要同步这个变更到本地。# 回到工作目录根目录 cd /path/to/workspace # 切换到主分支或你想同步到的分支 repo abandon feature-xyz # 可选放弃本地功能分支 repo checkout master # 切换到各个仓库的master分支 # 同步最新代码这会将已合入的变更拉取下来 repo sync -c -j8现在你的本地代码库就包含了刚才合入的修改可以基于此开始新的开发了。5. 高级技巧与疑难问题排查掌握了基本流程下面这些技巧和问题处理能力能让你更游刃有余。5.1 高效使用Repo命令repo forall在所有或指定项目中执行相同的Shell命令。例如想查看所有仓库的当前状态repo forall -c ‘git status -s’repo prune删除已合并的本地分支保持整洁。repo prune会清理所有项目中那些上游分支已不存在的本地分支。repo diff查看所有项目中的未提交更改。repo diff能给出一个统一的差异视图。repo info显示当前工作目录下所有项目的详细信息包括当前分支、提交、以及清单文件中的修订版本。处理清单文件有时你需要修改本地的清单文件来测试不同的代码组合。.repo/manifests/目录下可能有多个清单文件。你可以通过repo init -m another_manifest.xml来切换但这会重置你的工作区需谨慎。5.2 Gerrit评审流程中的常见问题问题1推送失败提示 “missing Change-Id in commit message”原因提交信息中没有Change-Id。通常是commit-msg钩子未安装或未生效。解决确保钩子已正确安装到.git/hooks/目录。对于已有提交但缺少Change-Id的情况可以使用git commit --amend重新编辑提交信息保存时钩子会自动添加。或者使用git rebase -i交互式变基来修改历史提交。问题2推送失败提示 “cannot merge” 或冲突原因在你开发的同时目标分支已经有了新的提交导致你的修改基础过旧。解决使用repo sync同步最新代码到本地。在你的功能分支上执行变基git rebase origin/master在具体项目目录下。解决可能出现的冲突然后继续变基。再次执行repo upload --cbr。--cbr参数会在上传前自动执行变基可以预防此问题。问题3一个功能涉及多个Change如何关联方法在repo upload时或者后续在Gerrit网页端为这些Change设置相同的Topic。这样在Gerrit的搜索界面可以通过Topic过滤方便评审者整体查看。在repo upload的交互提示中可以设置topic。问题4如何下载他人提交的Change到本地进行测试方法在Gerrit网页端每个Change页面都有一个“Download”下拉按钮里面提供了多种拉取该补丁集的命令例如通过git fetch和cherry-pick或者使用repo download命令如果配置了Gerrit远程。# 例如拉取项目 platform/framework/base 的 Change 12345, Patch Set 4 repo download platform/framework/base 12345/45.3 维护清单文件与本地修改对于需要定制化组件或使用内部私有仓库的团队维护自己的manifest仓库是必经之路。你通常会Fork上游的manifest仓库然后修改其中的default.xml或创建新的xml文件。关键标签解析manifest remote nameaosp fetchhttps://android.googlesource.com/ / remote namecompany fetchhttps://gerrit.company.com/ / default revisionmaster remoteaosp sync-j4 / project pathplatform/framework/base nameplatform_frameworks_base / project pathvendor/company/proprietary namevendor_company_proprietary remotecompany revisionstable / /manifestremote定义代码库的远程服务器。default设置默认属性如默认远程、默认分支、默认同步线程数。project定义一个子项目。path是本地路径name是远程仓库名相对于remote的fetch地址remote和revision可覆盖默认值。本地覆盖有时你不想修改manifest仓库只想临时测试某个仓库的不同版本。可以在工作目录根目录创建一个local_manifests文件夹在里面放置你的local_manifest.xml。Repo在同步时会合并这里的配置优先级最高。这在调试时非常有用。6. 团队协作规范与最佳实践工具用得好更要流程规范。以下是一些提升团队效率的经验。1. 提交信息规范格式统一严格执行首行摘要、空行、正文、标签的格式。关联Issue使用Bug:Test:Feature:等标签关联任务管理系统。描述清晰正文要说明“为什么”这么改而不仅仅是“改了啥”。这对于评审和日后回溯至关重要。2. 分支管理策略功能分支每个功能或Bug修复都使用repo start创建独立分支。分支命名采用dev/姓名缩写/功能简述或feature/PROJ-1234等有意义的名称。及时清理功能合入后使用repo abandon及时清理本地分支。定期使用repo prune。3. 评审文化小步快跑尽量保持Change的原子性和小巧一个Change只做一件事便于评审和回滚。及时响应作为作者对评审意见要及时回复或修改作为评审者应在约定时间内完成评审。** constructive**评审意见应对事不对人聚焦于代码改进。4. 持续集成CI集成将Gerrit与Jenkins等CI系统对接。配置CI在每次有新的Patch Set上传时自动运行编译和测试并将结果以“Verified”标签的形式反馈回Gerrit。这能极大提高评审效率提前发现集成问题。5. 备份与恢复Repo工作目录很大重新同步耗时。定期备份.repo目录尤其是manifests和project-objects可以加速在新机器上的环境搭建。可以使用rsync或tar进行增量备份。从最初的磕磕绊绊到后来的驾轻就熟Gerrit和Repo这套组合拳确实为大型代码库的管理带来了秩序。它强制推行的代码评审流程初期可能会让人觉得繁琐但长期来看它对代码质量的提升、知识在团队中的传播以及减少集成冲突的价值是不可估量的。最关键的是理解每个工具的设计初衷理顺它们之间的协作关系然后通过规范的流程和习惯让这套工具真正为团队赋能而不是成为负担。当你习惯了repo sync拉取整个世界repo upload推送修改并等待评审反馈的节奏后你会发现这种结构化的协作方式才是应对复杂项目开发的从容之道。