1. 项目概述为什么是Git与Gerrit的组合如果你在团队里写过代码尤其是规模稍大一点的团队大概率听说过Git。它就像代码世界的“时光机”加“平行宇宙生成器”让你能自由穿梭于代码的各个历史版本也能同时开展多个功能开发而不互相干扰。但Git本身更像一个强大的单兵武器当我们需要一支纪律严明的军队进行协同作战时就需要一个“指挥官”来制定规则、审核路线。这个指挥官就是Gerrit。我最初接触Gerrit是在一个大型的嵌入式项目里团队几十号人代码仓库巨大每天都有大量的合并请求。如果只用Git很快就会陷入“该合并谁的代码”、“谁的代码引入了Bug”、“功能分支满天飞”的混乱局面。Gerrit的出现完美地解决了这个问题。它本质上是一个基于Git的代码评审Code Review和仓库管理工具强制所有代码在合入主分支比如master或main前必须经过同行评审Peer Review。这不仅仅是流程上的约束更是提升代码质量、促进知识共享、保证项目健康度的核心实践。所以这篇笔记不是简单的命令罗列而是我多年在“Git Gerrit”这套组合拳下摸爬滚打的经验总结。我会从最基础的本地Git操作讲起一直深入到Gerrit评审流程中的各种实战技巧和避坑指南。无论你是刚接触版本控制的新手还是已经会用git add/commit/push但面对团队协作流程仍感困惑的开发者这篇文章都能给你提供一套从个人到团队的完整工作流视角。2. Git核心操作精要与本地工作流搭建在接触Gerrit之前我们必须把Git这个工具用得炉火纯青。很多人觉得Git命令多且杂其实核心思想就那几个理解了之后大部分命令都是这些思想的组合应用。2.1 仓库初始化与基础快照管理一切始于一个仓库Repository。你可以通过git init在本地创建一个全新的仓库或者用git clone url把远程仓库的完整历史拷贝到本地。这里有个细节git clone默认会把远程仓库的所有分支都拉下来但你在本地只会看到一个master或main分支这是默认分支。其他远程分支以origin/branch-name的形式存在你需要手动创建本地分支去跟踪它们。代码的提交Commit是Git的基石它保存了项目在某个时刻的完整快照。但提交不是一蹴而就的它遵循“工作区 - 暂存区 - 仓库”的三段式流程。工作区Working Directory就是你电脑上直接编辑文件的地方。暂存区Staging Area / Index一个中间区域用来精心准备下一次提交的内容。你可以只把修改的一部分文件甚至一个文件里的部分修改放入暂存区。仓库Repository存放所有提交历史的地方。对应的命令是git add file # 将工作区的修改添加到暂存区 git commit -m “描述” # 将暂存区的内容创建为一个新的提交注意git commit -a -m “描述”这个命令可以跳过git add直接提交所有已跟踪文件的修改。但它不会提交新增的未跟踪文件。对于新手我建议还是明确使用git add这能让你更清晰地控制提交内容避免误提交。2.2 分支策略功能分支与主分支的守护Git最强大的特性之一是分支。创建分支git branch name或git checkout -b name成本极低瞬间完成。健康的团队协作几乎都基于功能分支工作流Feature Branch Workflow。核心原则master/main分支是神圣的它应该始终保持可发布状态。任何新功能的开发、Bug的修复都必须在独立的分支上进行。开发新功能git checkout -b feature/awesome-new-feature修复紧急Buggit checkout -b hotfix/critical-issue在功能分支上你可以自由地进行多次commit就像在私人草稿本上写写画画。完成开发后你需要将你的工作整合回主分支。这里就有两个核心命令merge和rebase。git merge合并。它会在历史中创建一个新的“合并提交”明确记录了两个分支交汇的事实。历史清晰但可能会显得有些杂乱。git rebase变基。它会把你当前分支上的所有提交“重新播放”到目标分支通常是master的最新提交之后。结果是得到一条线性的、整洁的历史记录就像所有工作都是基于最新代码顺序完成的一样。实操心得在准备将本地分支推送到远程尤其是Gerrit之前我强烈推荐先对本地分支进行一次rebase操作。假设你在feature/xxx分支上开发主分支已经更新了。git checkout feature/xxx git fetch origin # 获取远程最新信息但不合并 git rebase origin/master # 将当前分支变基到最新的origin/master上这样做的好处是1解决潜在的合并冲突会在你本地完成不影响他人。2提交历史变得清晰便于评审者阅读。3在Gerrit中一个线性的提交历史更容易被通过。变基过程中如果遇到冲突Git会暂停让你解决冲突后执行git add .标记冲突已解决再执行git rebase --continue继续。2.3 状态查看、历史追溯与后悔药git status是你最好的朋友随时运行它看看工作区和暂存区是什么状态。git log是历史记录本使用git log --oneline --graph --all可以查看一个漂亮的、图形化的分支合并历史。人总会犯错Git提供了强大的“后悔药”机制但必须清楚每种“药”的副作用。修改最后一次提交git commit --amend。这非常有用比如你刚提交完发现漏了个文件或者提交信息写错了。它可以修改最后一次提交的内容和信息而不会产生一个新的提交。警告如果该提交已经推送到远程强制推送git push --force可能会给协作者带来麻烦。在Gerrit环境中对已推送的变更使用amend并强制推送是常规操作因为Gerrit的变更集Change就是以提交为单位的。撤销工作区的修改git checkout -- file。危险这会丢弃该文件在工作区的所有未暂存修改且不可恢复。用之前请三思。撤销暂存区的修改git reset HEAD file。这会把文件从暂存区挪回工作区修改内容还在只是状态变了。临时储藏工作现场git stash。当你正在一个分支上工作突然需要切到另一个分支处理紧急事务时可以用它把当前未提交的修改临时保存起来清空工作区。处理完后用git stash pop恢复。3. Gerrit核心概念与代码评审流程实战当你把本地Git玩转后我们就进入了团队协作的领域——Gerrit。它的核心模型是“变更集Change驱动”。3.1 从Git Push到Gerrit Change在普通的Git工作流中你git push就直接更新了远程分支。在Gerrit中git push的目的地不是分支而是一个特殊的引用ref。 标准的推送命令会变成git push origin HEAD:refs/for/master注意这里的refs/for/master。refs/for/是Gerrit的魔法前缀。这行命令的意思是“将我的当前分支HEAD推送到Gerrit服务器目标是master分支但请为我创建一个待评审的变更集Change。”推送成功后Gerrit会生成一个唯一的变更集URL通常包含一个Change-Id例如I0a1b2c3d4e5...。这个Change-Id至关重要它存在于你提交信息的尾部通常由commit-msg钩子自动添加是Gerrit跟踪同一变更多次更新的依据。3.2 评审界面与协作互动打开Gerrit生成的Change页面你会看到以下核心部分变更详情显示了提交信息、作者、所属分支等。差异对比Diff这是评审的核心区域默认以并排Side-by-Side视图展示代码的每一行修改。评审者可以在这里对任意一行代码发表评论Comment。评审意见Review评审者可以给出评分。最常见的是Code-Review2批准可合并1看起来不错但需要其他人批准0无意见-1我觉得需要修改-2请勿合并。Verified1通过自动化验证如CI构建成功-1验证失败如编译错误或测试不通过。活动流记录所有评论、评分、状态更新的时间线。作为提交者你的任务是及时回复评审者的每一个行内评论。可以解释设计思路也可以直接回复“Done”并附上修改后的代码。如果评审者要求修改你需要在本地原提交上修改然后使用git commit --amend。确保Change-Id保持不变。之后再次推送到refs/for/master。Gerrit会通过相同的Change-Id识别出这是对原变更集的更新而不是一个新的变更。原页面会自动刷新显示新的补丁集Patch Set所有旧的评论会被标记为“已解决”。3.3 提交信息的艺术与Change-IdGerrit环境下的提交信息要求更严格。一个规范的提交信息格式如下简要概述不超过50字 空一行 详细的说明性正文。解释修改了什么为什么这么修改而不是如何修改代码自己会说话。 可以分段落使用项目符号。 Bug: [问题追踪系统ID如 JIRA-123] Change-Id: I0a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t第一行至关重要它是Change列表的标题必须清晰扼要。Body部分说明“为什么”比“做了什么”更重要。关联的Bug或需求ID必须写上。Change-Id由commit-msg钩子自动生成。务必确保它存在且唯一。如果没有Gerrit会将每次推送视为全新的变更。注意事项安装Gerrit提供的commit-msg钩子是第一步。你可以从Gerrit服务器的/tools/hooks/目录下载或通过scp命令获取然后拷贝到项目的.git/hooks/目录下并确保其有可执行权限。没有这个钩子后续工作流会非常麻烦。4. 高级工作流依赖变更、冲突解决与批量操作在实际项目中情况往往更复杂。你的功能可能依赖于另一个正在评审的变更或者多个变更需要一起测试、一起合并。4.1 处理依赖变更Depends-On假设你的变更A依赖于同事的变更BB尚未合入。你需要在A的提交信息中或Gerrit的Change页面添加依赖关系。在变更A的提交信息正文中添加一行Depends-On: ChangeId-of-B或者在Gerrit网页上变更A的页面在“包括父级”的选项中将变更B添加为依赖。这样Gerrit会知道A必须在B之后合并。在测试时CI系统也可以自动获取B和A的代码一起进行验证。4.2 解决冲突与重新变基当你的变更在评审期间目标分支如master向前推进了可能导致你的代码出现冲突。Gerrit的CI验证Verified可能会失败。 此时你需要git fetch origin获取远端最新代码。git rebase origin/master将你的分支变基到最新基准。强烈建议在变基前确保本地分支的所有修改都已提交。解决变基过程中出现的冲突。完成变基后使用git commit --amend仅仅是为了确保Change-Id不变如果rebase过程没有修改提交可能不需要但通常建议做一次。实际上在rebase交互界面中你可以直接修改每个提交。再次推送git push origin HEAD:refs/for/master。Gerrit会识别出这是基于相同Change-Id的新补丁集并替换旧的。4.3 批量提交与交互式变基有时本地开发了一堆提交但为了评审清晰需要整理合并。这时要用到交互式变基Interactive Rebasegit rebase -i origin/master这会打开一个编辑器列出你当前分支上所有独有的提交。你可以squash (s)将多个提交合并成一个并重新编辑提交信息。这是整理本地琐碎提交准备一个整洁变更集的利器。reword (r)修改某个提交的提交信息。edit (e)暂停在某个提交允许你修改文件内容。实操心得在推送到Gerrit前花时间做一次git rebase -i整理历史是非常值得的。理想情况下一个功能或一个Bug修复对应一个逻辑清晰的提交。避免将“代码格式化”和“功能修改”混在同一个提交里。如果修改很大可以拆分成多个逻辑独立的变更集并设置好依赖关系这样更利于评审。5. 常见问题排查与实战技巧实录即使流程再熟悉坑也总是有的。下面是一些我踩过的坑和总结的技巧。5.1 推送失败与权限问题错误信息可能原因解决方案! [remote rejected] HEAD - refs/for/master (no common ancestry)本地仓库历史与远程仓库完全不相关比如本地初始化错了。检查是否clone了正确的仓库或者尝试git pull --rebase看看。! [remote rejected] HEAD - refs/for/master (failed to lock)网络问题或服务器端临时锁冲突。稍等片刻重试。! [remote rejected] HEAD - refs/for/master (change XXX closed)尝试更新一个已经合并或废弃的变更。检查Change状态。如果已合并基于新主分支创建新变更。Permission denied (publickey).SSH密钥未配置或未添加到Gerrit账号。检查~/.ssh/id_rsa.pub内容是否已完整添加到Gerrit用户的SSH Keys设置中。关于SSH配置Gerrit通常使用SSH协议。确保你的~/.ssh/config文件配置了正确的主机和端口Host gerrit.company.com HostName gerrit.company.com Port 29418 User your_username IdentityFile ~/.ssh/id_rsa端口29418是Gerrit默认的SSH端口。5.2 Change-Id丢失与补救这是最常见的问题之一。推送时提示“Missing Change-Id”。预防确保commit-msg钩子已正确安装并生效。每次git commit后检查提交信息末尾是否自动添加了Change-Id:行。补救提交尚未推送git log --oneline找到需要添加Change-Id的提交的哈希值比如abc123。git commit --amend修改该提交。不要动提交信息直接保存退出。此时钩子会为这次amend操作生成新的Change-Id。或者你也可以手动从其他提交拷贝一个Change-Id过来不推荐。补救提交已推送但被拒绝按照上述方法在本地添加Change-Id。再次执行推送命令。5.3 评审卡点与沟通技巧评审迟迟没有动静可以礼貌地在变更下留言“Ping”或“Could you please take a look?”或者直接联系评审者。有时评审者只是太忙遗漏了。收到“-1”或“-2”不要有抵触情绪。仔细阅读每一条评论理解评审者的关切。如果不同意用代码和事实礼貌地讨论。大部分情况下评审者的意见都是有价值的能帮你发现盲点。如何给出好的评审意见作为评审者时避免只说“这不好”。要具体指出问题所在并尽可能给出改进建议或参考。多问“为什么这样设计”关注代码的可读性、可维护性、边界条件和性能影响而不仅仅是风格问题风格问题应尽量通过自动化工具解决。5.4 与IDE及CI/CD集成IDE插件IntelliJ IDEA、VSCode等主流IDE都有Gerrit插件可以在IDE内直接查看变更、发表评论大幅提升效率。Git配置别名在~/.gitconfig中配置别名让命令更简短。[alias] ps push origin HEAD:refs/for/master lol log --oneline --graph --all ri rebase -i origin/master之后就可以用git ps推送用git lol看日志了。CI/CD集成Gerrit的“Verified”标签通常与Jenkins等CI系统集成。CI会监听refs/for/的推送自动拉取代码进行编译、测试。只有通过验证Verified1且评审通过Code-Review2的变更才能被合并。确保你的本地修改能通过编译和基础测试再推送可以节省CI资源和时间。这套“Git Gerrit”的流程初看步骤繁多但一旦习惯它会成为保障团队代码质量的强大基础设施。核心在于理解其设计哲学所有合并皆评审所有提交皆可追溯。它通过一个轻量级的强制流程将良好的开发实践固化下来最终让团队里的每个人都能更高效、更安心地贡献代码。