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 - 修复紧急Bug：
git 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-Review：
+2（批准，可合并），+1（看起来不错，但需要其他人批准），0（无意见），-1（我觉得需要修改），-2（请勿合并）。 - Verified：
+1（通过自动化验证，如CI构建成功），-1（验证失败，如编译错误或测试不通过）。
- Code-Review：
- 活动流：记录所有评论、评分、状态更新的时间线。
作为提交者，你的任务是：
- 及时回复评审者的每一个行内评论。可以解释设计思路，也可以直接回复“Done”并附上修改后的代码。
- 如果评审者要求修改，你需要在本地原提交上修改，然后使用
git commit --amend。确保Change-Id保持不变。之后再次推送到refs/for/master。Gerrit会通过相同的Change-Id识别出这是对原变更集的更新，而不是一个新的变更。原页面会自动刷新，显示新的补丁集（Patch Set），所有旧的评论会被标记为“已解决”。
3.3 提交信息的艺术与Change-Id
Gerrit环境下的提交信息要求更严格。一个规范的提交信息格式如下：
简要概述（不超过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依赖于同事的变更B（B尚未合入）。你需要在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 Rebase）：
git 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/mastergit ps推送，用git lol看日志了。 - CI/CD集成：Gerrit的“Verified”标签通常与Jenkins等CI系统集成。CI会监听
refs/for/的推送，自动拉取代码进行编译、测试。只有通过验证（Verified+1）且评审通过（Code-Review+2）的变更才能被合并。确保你的本地修改能通过编译和基础测试再推送，可以节省CI资源和时间。
这套“Git + Gerrit”的流程，初看步骤繁多，但一旦习惯，它会成为保障团队代码质量的强大基础设施。核心在于理解其设计哲学：所有合并皆评审，所有提交皆可追溯。它通过一个轻量级的强制流程，将良好的开发实践固化下来，最终让团队里的每个人都能更高效、更安心地贡献代码。
