Git与Gerrit协同工作流：从版本控制到代码审查的完整实践指南

1. 从版本控制到代码审查：为什么需要 Git 与 Gerrit 的组合？

如果你是一名刚入行的开发者，或者是从 SVN 时代转型过来的“老兵”，第一次听到 Git 和 Gerrit 这两个词时，可能会有点懵。Git 我知道，是现在最流行的分布式版本控制系统，那 Gerrit 又是什么？它和 Git 是什么关系？为什么很多大型项目，比如 Android 开源项目，会同时使用它们？这就像你有了一个功能强大的私人仓库（Git），但还需要一个专业的物流分拣中心和质检流水线（Gerrit），才能确保货物（代码）在进入中央大仓（主代码库）前是完好、合规且高质量的。今天，我就结合自己多年在团队协作开发中的踩坑经验，来彻底讲清楚 Git 和 Gerrit 的基础概念、核心工作流以及它们如何珠联璧合，打造出高效、安全的代码交付管道。无论你是想搭建团队代码平台，还是单纯想理解这套流程以便更好地参与项目，这篇文章都能给你一个清晰的蓝图。

简单来说，Git 解决了“代码怎么写”和“版本怎么存”的问题，而 Gerrit 则聚焦于“代码怎么交”和“质量怎么管”。Git 赋予每个开发者完整的代码库和历史，让你可以离线工作、自由分支。但当你要把劳动成果贡献到共享的、权威的项目主线时，如果没有一个受控的入口，很快就会陷入混乱：代码质量参差不齐、提交信息混乱、历史线杂乱无章。Gerrit 就是这个“守门人”，它强制所有推送到共享仓库的代码都必须经过一个基于 Web 的代码审查流程，只有审查通过（并可能通过自动化测试）后，代码才会被真正合入。接下来，我们就深入拆解这套组合拳的每一个细节。

2. Git 核心概念再透视：不只是“保存代码”

很多人把 Git 等同于“保存代码的工具”，这其实大大低估了它的能力。Git 的本质是一个内容寻址文件系统，其上构建了一套版本控制逻辑。理解这个底层设计，很多操作就会豁然开朗。

2.1 仓库、工作区、暂存区与提交

这是 Git 最核心的四个概念，构成了代码从修改到保存的完整路径。

1. 仓库：即.git目录，是 Git 存储所有元数据和对象数据库的地方。它包含了完整的项目历史记录。当你执行git clone时，就是复制了整个仓库。
2. 工作区：就是你电脑上看到的项目文件目录，在这里你进行编辑、新增、删除文件。
3. 暂存区：一个介于工作区和仓库之间的缓存区域。你可以把它想象成快递打包台。工作区的改动（新增、修改的文件）通过git add命令被放到这个“打包台”上，准备生成一个快照。
4. 提交：一个提交对象，它永久记录了暂存区在某个时间点的快照，以及作者、提交信息、父提交等元数据。执行git commit就是将“打包台”上的所有内容，打成一个不可更改的包裹，存入仓库的历史中。

注意：git commit -a这个命令看似方便，它会自动暂存所有已跟踪文件的修改然后提交，跳过了显式使用git add的步骤。但在严谨的工作流中，我不推荐新手常用它，因为它让你失去了分阶段、有选择地组织提交的机会，容易产生包含不相关改动的“大杂烩”提交。

2.2 分支：低成本并行的魔法

Git 的分支是其分布式设计的精髓所在。在其他版本控制系统中，创建一个分支可能意味着复制整个项目目录，成本高昂。而在 Git 中，分支本质上只是一个指向某个提交对象的可变指针。

• 创建分支：git branch feature-x仅仅是新建了一个名为feature-x的指针，指向你当前的提交。开销极小。
• 切换分支：git checkout feature-x或git switch feature-x做了两件事：将 HEAD 指针指向feature-x分支，并用feature-x指向的提交快照更新你的工作区。
• 分支合并：当你完成feature-x的开发后，通过git merge将其合并回main分支。Git 会尝试自动进行三方合并（共同祖先、当前分支、待合并分支），如果成功，会产生一个新的合并提交。

一个关键技巧：在团队协作中，保持主分支（如main,master）的线性、整洁历史非常重要。这意味着要尽量避免在main分支上直接进行git merge产生分叉。更推荐使用git rebase。

2.3 Rebase 与 Merge 的抉择

这是 Git 学习路上的一个经典选择题。两者都能整合不同分支的修改，但方式截然不同。

• Merge：非破坏性操作。它创建一个新的合并提交，拥有两个父提交，将分支历史原样保留。历史会如实反映开发的并行过程，但可能会显得复杂。

  git checkout main git merge feature-x

• Rebase：变基。它提取你在当前分支上的所有新提交，在目标分支（通常是上游分支）的最新提交之上重新“播放”一遍。结果是使得当前分支的历史看起来像是直接在目标分支的最新点之后进行的线性开发。

  git checkout feature-x git rebase main # 解决可能出现的冲突后，feature-x 分支的基点就变成了 main 的最新提交

如何选择？

• 使用 Merge：当你需要保留完整的合并历史，或者分支是公共的（其他人可能基于它工作），因为 rebase 会重写历史，给协作者带来麻烦。
• 使用 Rebase：在将本地特性分支合入主分支之前，强烈建议先 rebase 到最新的主分支上。这样做的好处是：主分支的历史是一条干净的直线，便于回溯和二分查找问题。这也是与 Gerrit 协作时的标准前置操作。

实操心得：我个人的工作流是：在本地特性分支开发时，定期git rebase origin/main以同步上游改动，减少最终合并时的冲突。在推送代码审查（Gerrit）前，务必再执行一次 rebase，确保我的更改是基于项目最新代码的。这能极大提高审查通过率和代码集成效率。

2.4 远程协作：Push, Pull, Fetch

分布式意味着每个开发者都有完整的仓库。远程仓库（如 GitHub, GitLab, Gerrit 服务器上的仓库）是一个大家约定好的“中心节点”，用于同步代码。

• git fetch <remote>：这是一个“只下载”操作。它会从远程仓库拉取所有你本地还没有的数据（比如别人新建的分支和提交），更新你的本地远程跟踪分支（如origin/main），但不会自动合并到你的当前工作分支。这是最安全的方式，让你先看看别人做了什么。
• git pull <remote>：这实际上是git fetch后紧接着git merge的快捷操作。它把远程的最新内容拉下来并立即尝试合并到你当前分支。在复杂分支状态下，直接pull有时会产生令人困惑的合并提交，我更倾向于先fetch，再决定是merge还是rebase。
• git push <remote> <branch>：将你本地指定分支的提交上传到远程仓库。在 Gerrit 的语境下，推送行为有特殊规则，我们后面会详细讲。

3. Gerrit 核心概念解析：代码入库的守门员

如果说 Git 给了开发者自由的创作空间，那么 Gerrit 就是确保作品能规范进入“艺术馆”的策展人。它是一个基于 Git 版本控制的代码审查和项目管理工具。

3.1 Gerrit 的核心模型：Change 与 Patch Set

这是理解 Gerrit 工作流的基础。在 Gerrit 中，没有直接的git push to main。

1. Change：在 Gerrit 中，一个“变更”是代码审查的基本单位。它对应一次代码提交（Commit），但处于“待审查”状态。你可以把它看作一个挂在半空中的“提案”或“工单”。
2. Patch Set：补丁集。当审查者提出意见，你需要修改代码时，你不会在原来的提交上修改（因为 Git 提交是不可变的），而是会基于原提交产生一个新的提交。在 Gerrit 中，这个新的提交就是原 Change 的一个新的Patch Set。一个 Change 可以包含多个按顺序编号的 Patch Set（如 Patch Set 1, 2, 3），记录了代码的迭代改进过程。

工作流程比喻：你写了一篇论文初稿（Patch Set 1）交给导师（Gerrit）。导师批注后，你修改论文，提交了第二版（Patch Set 2）。这个过程可以重复，直到导师满意，批准论文发表（合并入主分支）。

3.2 引用命名空间：推送到refs/for/

这是 Gerrit 与原生 Git 交互的关键魔法。在普通的 Git 服务器上，你推送到refs/heads/main就是直接更新主分支。在 Gerrit 上，禁止直接推送到分支引用。

你必须推送到一个特殊的引用命名空间：refs/for/<branch-name>。

# 错误：这将失败或被拒绝 git push origin main # 正确：将当前分支推送到 Gerrit，针对 main 分支创建一个待审查的 Change git push origin HEAD:refs/for/main

当你推送到refs/for/main，Gerrit 会：

1. 接收你的提交。
2. 在数据库中创建一个新的Change，状态为New。
3. 为这个 Change 分配一个唯一的编号和 URL。
4. 将你的提交存储为该 Change 的第一个Patch Set。
5. 通知配置好的审查者。

3.3 代码审查流程与生命周期

一个 Change 在 Gerrit 中的典型生命周期如下：

1. New：变更刚被创建，等待审查。
2. Under Review：审查者正在查看代码。审查者可以在代码行上添加评论，提出疑问或建议。
3. Needs Change：审查者给出了“-1”或“-2”的评分（取决于项目配置），要求作者修改代码。作者需要根据反馈修改代码，生成新的提交，并推送到同一个 Change 上形成新的 Patch Set。

   # 在本地修改代码后... git add . git commit --amend # 注意：使用 --amend 修改上一次提交，保持Change ID不变 git push origin HEAD:refs/for/main # Gerrit 会自动识别这是同一个 Change，并创建 Patch Set 2

4. Approved：审查者给出了“+1”或“+2”的评分，表示认可代码。
5. Verified：自动化测试系统（如 Jenkins）运行测试，通过后给出“+1”的 Verified 标签。
6. Ready to Submit：当 Change 同时满足了代码审查（如至少一个+2）和自动化验证（+1 Verified）的条件后，状态变为可提交。
7. Submitted：具有提交权限的人（可能是审查者自己或集成者）点击“Submit”按钮。Gerrit 会执行一次最终的合并操作，将这个 Change 的代码快进合并到目标分支（如main）。此时，Change 状态关闭。
8. Abandoned：作者主动放弃这个变更。

3.4 Change-Id：Gerrit 的追踪密钥

你可能会好奇，Gerrit 如何知道一个新的提交是属于一个已存在的 Change，而不是创建一个新的 Change？答案就是Change-Id。

Change-Id 是一个由 Gerrit 生成的唯一哈希字符串，通常以I开头。它被放置在提交信息的最后一行（Footer部分）。当你使用git commit --amend时，如果提交信息中已包含 Change-Id，Gerrit 的客户端钩子（hook）会保留它，从而让 Gerrit 服务器知道这是对现有 Change 的更新。

如何获取 Change-Id？

1. 最方便的方式是安装 Gerrit 提供的commit-msg钩子。安装后，每次git commit，该钩子会自动在提交信息末尾生成并插入 Change-Id。
2. 首次推送创建 Change 后，Gerrit 也会在 Web 界面上显示该 Change-Id，你可以手动复制到后续的提交信息中（不推荐，易出错）。

注意事项：务必确保团队每个成员都正确配置了commit-msg钩子。否则，每次修改后推送都会创建新的、孤立的 Change，导致审查链断裂，管理混乱。这是新手搭建 Gerrit 环境时最容易踩的坑之一。

4. Git 与 Gerrit 协同工作流实战

理解了核心概念，我们来看一个完整的、从零开始的代码贡献流程。假设你要为一个使用 Gerrit 管理的开源项目修复一个 Bug。

4.1 环境准备与初始配置

1. 安装 Git：从官网下载并安装。安装时，注意选择将 Git 添加到系统 PATH，并选择将git bash作为默认命令行工具。
2. 配置用户信息：这是提交者的身份标识，至关重要。

   git config --global user.name "你的姓名" git config --global user.email "你的邮箱@公司.com" # 这个邮箱必须与你在 Gerrit 服务器上注册的邮箱一致，否则权限会出问题。

3. 生成 SSH 密钥并注册：Gerrit 通常使用 SSH 协议认证。

   ssh-keygen -t ed25519 -C "your_email@example.com" # 生成密钥对 # 将公钥（~/.ssh/id_ed25519.pub 文件内容）添加到 Gerrit 账号的 SSH Keys 设置中。

4. 克隆仓库：

   git clone ssh://<username>@<gerrit-server>:29418/<project-name>.git cd <project-name>

   注意 Gerrit 仓库的 SSH 端口通常是29418。

4.2 开发与提交本地更改

1. 获取最新代码并创建特性分支：永远不要在本地main分支上直接开发。

   git fetch origin # 获取远程最新信息 git checkout -b fix-typo origin/main # 基于远程主分支创建并切换到新分支

2. 安装 commit-msg 钩子：这是与 Gerrit 协同的关键一步。通常项目仓库的根目录下或有说明文档。

   # 常见方法：使用 scp 命令从 Gerrit 服务器下载钩子脚本 scp -p -P 29418 <username>@<gerrit-server>:hooks/commit-msg .git/hooks/ chmod +x .git/hooks/commit-msg # 确保钩子可执行

3. 进行代码修改：修复你的 Bug。
4. 提交更改：

   git add <修改的文件> git commit

   执行git commit后，会自动打开编辑器让你填写提交信息。提交信息格式非常重要：
   • 第一行：简短的摘要（不超过50字符）。
   • 空一行。
   • 正文：详细描述修改的原因、内容、影响。
   • 空一行。
   • 底部：由钩子自动生成的Change-Id: Ixxx...。 保存退出后，钩子会自动在信息末尾插入 Change-Id。

4.3 推送代码到 Gerrit 进行审查

1. 在推送前变基：确保你的分支是基于最新的origin/main，这能减少冲突，让审查者基于最新代码评审。

   git fetch origin git rebase origin/main # 如果发生冲突，解决冲突后执行 git rebase --continue

2. 执行推送：

   git push origin HEAD:refs/for/main

3. 查看结果：命令执行成功后，命令行会输出一个 URL，类似https://<gerrit-server>/c/<project>/+/<change-number>。打开这个链接，你就看到了刚刚创建的 Change 页面。

4.4 处理审查意见并更新补丁集

1. 查看评论：审查者在代码行旁添加了评论。
2. 本地修改：根据评论，在本地分支上修改代码。
3. 修改提交：不要创建新的提交。使用--amend选项修改上一次提交。

   git add <修改的文件> git commit --amend

   在打开的编辑器中，你可以更新提交信息（比如在末尾加上Fixed: 根据review意见，修正了XXX），但千万不要删除或修改已有的 Change-Id 行。保存退出。
4. 推送更新：再次推送到相同的refs/for/main引用。

   git push origin HEAD:refs/for/main

   Gerrit 会识别出这是同一个 Change-Id，从而在原有的 Change 下创建Patch Set 2。所有旧的评论会被标记为“已修复”，审查者可以专注于新的改动。

4.5 代码合入与后续操作

1. 等待标签：当 Change 获得足够的Code-Review +2和Verified +1标签后，状态变为Ready to Submit。
2. 提交变更：具有提交权限的人点击“Submit”按钮。Gerrit 会执行一次快进合并。
3. 同步本地仓库：变更合入后，你需要更新你的本地主分支和特性分支。

   git checkout main git pull origin main # 拉取已合入的变更 git branch -d fix-typo # 删除已合并的本地特性分支

5. 常见问题与排查技巧实录

在实际使用 Git 与 Gerrit 的过程中，你一定会遇到各种问题。这里记录了一些典型场景和我的解决思路。

5.1 推送失败：权限不足或引用不存在

• 问题：git push失败，提示Permission denied或remote: ERROR: <branch> not found。
• 排查：
  1. 检查 SSH 密钥：ssh -Tp 29418 <username>@<gerrit-server>测试连接。确保公钥已正确添加到 Gerrit 账号。
  2. 检查推送引用：确认你推送到的是refs/for/<branch>而不是refs/heads/<branch>。
  3. 检查目标分支名：确认origin/main是否存在。有时主分支叫master。

5.2 推送后创建了新 Change，而不是更新旧 Change

• 问题：修改代码后git commit --amend并推送，结果 Gerrit 上出现了一个全新的 Change，旧的 Change 仍然存在。
• 原因：提交信息中的Change-Id 丢失或改变了。
• 解决：
  1. 确保钩子已安装：检查.git/hooks/commit-msg文件是否存在且可执行。
  2. 检查提交信息：git log --oneline -1查看最新提交，确认末尾有Change-Id: Ixxx...。
  3. 修复方法：找到旧 Change 的 Change-Id（在 Gerrit Web 页面上），复制它。然后使用git commit --amend，在编辑器中手动将正确的 Change-Id 粘贴到提交信息末尾（覆盖错误的或补充缺失的）。最后强制推送一次：git push origin HEAD:refs/for/main -f。注意：强制推送需谨慎，仅在你确定要覆盖时使用。

5.3 变基或合并时发生冲突

• 问题：执行git rebase origin/main或git pull时提示冲突。
• 解决流程：
  1. 不要慌。冲突是多人协作的常态。
  2. 执行git status查看哪些文件冲突。
  3. 打开冲突文件，你会看到<<<<<<<，=======，>>>>>>>标记。这是 Git 标记的冲突区块，你需要手动编辑文件，保留你想要的内容，删除这些标记。
  4. 解决完所有冲突文件后，使用git add <file>标记每个冲突已解决的文件。
  5. 如果是 rebase 过程，执行git rebase --continue。如果是 merge 过程，执行git commit（会弹出预填的合并信息）。
  6. 强烈建议：在解决冲突后，运行一遍项目测试，确保你的修改没有破坏任何功能。

5.4 Gerrit 页面显示 “Missing Change-Id in commit message”

• 问题：推送后，Gerrit Change 页面报错，无法识别提交。
• 原因：提交信息中没有 Change-Id，钩子可能未生效。
• 解决：
  1. 对于已推送的提交，在本地使用git commit --amend手动添加正确的 Change-Id（从错误信息或旧 Change 页面获取），然后强制推送。
  2. 对于未来的提交，彻底检查并安装commit-msg钩子。可以尝试重新下载：curl -Lo .git/hooks/commit-msg <gerrit-server>/tools/hooks/commit-msg; chmod +x .git/hooks/commit-msg。

5.5 如何下载他人提交的特定 Patch Set 进行测试？

• 场景：你需要将同事提交审查的某个 Patch Set 拉到本地进行测试或验证。
• 方法：Gerrit 为每个 Patch Set 都提供了方便的 Git 引用。
  1. 在 Gerrit Change 页面，找到对应的 Patch Set 编号（如 PS2）。
  2. 在页面右侧或下载区域，找到Download下拉菜单，选择Checkout或Pull指令。
  3. 你会看到类似git fetch ssh://... refs/changes/XX/123456/2 && git checkout FETCH_HEAD的命令。复制并在你的仓库目录下执行，即可将那个特定的补丁集拉取到本地并切换到该状态。

下表总结了一些常见问题的快速应对策略：

掌握 Git 是开发者的基本功，而理解 Gerrit 则是融入现代、严谨的协作开发文化的钥匙。这套组合的核心思想是：用 Git 赋予个体开发的灵活与自由，用 Gerrit 保障团队交付的质量与秩序。刚开始接触时，可能会觉得流程繁琐，但一旦习惯，你会发现自己提交的代码质量更高，团队协作也更顺畅。最重要的实操习惯就是：勤变基、写清晰的提交信息、用好钩子、仔细看审查评论。剩下的，就是在一次次提交、审查、迭代中积累经验了。