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 最核心的四个概念构成了代码从修改到保存的完整路径。仓库即.git目录是 Git 存储所有元数据和对象数据库的地方。它包含了完整的项目历史记录。当你执行git clone时就是复制了整个仓库。工作区就是你电脑上看到的项目文件目录在这里你进行编辑、新增、删除文件。暂存区一个介于工作区和仓库之间的缓存区域。你可以把它想象成快递打包台。工作区的改动新增、修改的文件通过git add命令被放到这个“打包台”上准备生成一个快照。提交一个提交对象它永久记录了暂存区在某个时间点的快照以及作者、提交信息、父提交等元数据。执行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-xRebase变基。它提取你在当前分支上的所有新提交在目标分支通常是上游分支的最新提交之上重新“播放”一遍。结果是使得当前分支的历史看起来像是直接在目标分支的最新点之后进行的线性开发。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。Change在 Gerrit 中一个“变更”是代码审查的基本单位。它对应一次代码提交Commit但处于“待审查”状态。你可以把它看作一个挂在半空中的“提案”或“工单”。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/mainGerrit 会接收你的提交。在数据库中创建一个新的Change状态为New。为这个 Change 分配一个唯一的编号和 URL。将你的提交存储为该 Change 的第一个Patch Set。通知配置好的审查者。3.3 代码审查流程与生命周期一个 Change 在 Gerrit 中的典型生命周期如下New变更刚被创建等待审查。Under Review审查者正在查看代码。审查者可以在代码行上添加评论提出疑问或建议。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 2Approved审查者给出了“1”或“2”的评分表示认可代码。Verified自动化测试系统如 Jenkins运行测试通过后给出“1”的 Verified 标签。Ready to Submit当 Change 同时满足了代码审查如至少一个2和自动化验证1 Verified的条件后状态变为可提交。Submitted具有提交权限的人可能是审查者自己或集成者点击“Submit”按钮。Gerrit 会执行一次最终的合并操作将这个 Change 的代码快进合并到目标分支如main。此时Change 状态关闭。Abandoned作者主动放弃这个变更。3.4 Change-IdGerrit 的追踪密钥你可能会好奇Gerrit 如何知道一个新的提交是属于一个已存在的 Change而不是创建一个新的 Change答案就是Change-Id。Change-Id 是一个由 Gerrit 生成的唯一哈希字符串通常以I开头。它被放置在提交信息的最后一行Footer部分。当你使用git commit --amend时如果提交信息中已包含 Change-IdGerrit 的客户端钩子hook会保留它从而让 Gerrit 服务器知道这是对现有 Change 的更新。如何获取 Change-Id最方便的方式是安装 Gerrit 提供的commit-msg钩子。安装后每次git commit该钩子会自动在提交信息末尾生成并插入 Change-Id。首次推送创建 Change 后Gerrit 也会在 Web 界面上显示该 Change-Id你可以手动复制到后续的提交信息中不推荐易出错。注意事项务必确保团队每个成员都正确配置了commit-msg钩子。否则每次修改后推送都会创建新的、孤立的 Change导致审查链断裂管理混乱。这是新手搭建 Gerrit 环境时最容易踩的坑之一。4. Git 与 Gerrit 协同工作流实战理解了核心概念我们来看一个完整的、从零开始的代码贡献流程。假设你要为一个使用 Gerrit 管理的开源项目修复一个 Bug。4.1 环境准备与初始配置安装 Git从官网下载并安装。安装时注意选择将 Git 添加到系统 PATH并选择将git bash作为默认命令行工具。配置用户信息这是提交者的身份标识至关重要。git config --global user.name 你的姓名 git config --global user.email 你的邮箱公司.com # 这个邮箱必须与你在 Gerrit 服务器上注册的邮箱一致否则权限会出问题。生成 SSH 密钥并注册Gerrit 通常使用 SSH 协议认证。ssh-keygen -t ed25519 -C your_emailexample.com # 生成密钥对 # 将公钥~/.ssh/id_ed25519.pub 文件内容添加到 Gerrit 账号的 SSH Keys 设置中。克隆仓库git clone ssh://usernamegerrit-server:29418/project-name.git cd project-name注意 Gerrit 仓库的 SSH 端口通常是29418。4.2 开发与提交本地更改获取最新代码并创建特性分支永远不要在本地main分支上直接开发。git fetch origin # 获取远程最新信息 git checkout -b fix-typo origin/main # 基于远程主分支创建并切换到新分支安装 commit-msg 钩子这是与 Gerrit 协同的关键一步。通常项目仓库的根目录下或有说明文档。# 常见方法使用 scp 命令从 Gerrit 服务器下载钩子脚本 scp -p -P 29418 usernamegerrit-server:hooks/commit-msg .git/hooks/ chmod x .git/hooks/commit-msg # 确保钩子可执行进行代码修改修复你的 Bug。提交更改git add 修改的文件 git commit执行git commit后会自动打开编辑器让你填写提交信息。提交信息格式非常重要第一行简短的摘要不超过50字符。空一行。正文详细描述修改的原因、内容、影响。空一行。底部由钩子自动生成的Change-Id: Ixxx...。 保存退出后钩子会自动在信息末尾插入 Change-Id。4.3 推送代码到 Gerrit 进行审查在推送前变基确保你的分支是基于最新的origin/main这能减少冲突让审查者基于最新代码评审。git fetch origin git rebase origin/main # 如果发生冲突解决冲突后执行 git rebase --continue执行推送git push origin HEAD:refs/for/main查看结果命令执行成功后命令行会输出一个 URL类似https://gerrit-server/c/project//change-number。打开这个链接你就看到了刚刚创建的 Change 页面。4.4 处理审查意见并更新补丁集查看评论审查者在代码行旁添加了评论。本地修改根据评论在本地分支上修改代码。修改提交不要创建新的提交。使用--amend选项修改上一次提交。git add 修改的文件 git commit --amend在打开的编辑器中你可以更新提交信息比如在末尾加上Fixed: 根据review意见修正了XXX但千万不要删除或修改已有的 Change-Id 行。保存退出。推送更新再次推送到相同的refs/for/main引用。git push origin HEAD:refs/for/mainGerrit 会识别出这是同一个 Change-Id从而在原有的 Change 下创建Patch Set 2。所有旧的评论会被标记为“已修复”审查者可以专注于新的改动。4.5 代码合入与后续操作等待标签当 Change 获得足够的Code-Review 2和Verified 1标签后状态变为Ready to Submit。提交变更具有提交权限的人点击“Submit”按钮。Gerrit 会执行一次快进合并。同步本地仓库变更合入后你需要更新你的本地主分支和特性分支。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。排查检查 SSH 密钥ssh -Tp 29418 usernamegerrit-server测试连接。确保公钥已正确添加到 Gerrit 账号。检查推送引用确认你推送到的是refs/for/branch而不是refs/heads/branch。检查目标分支名确认origin/main是否存在。有时主分支叫master。5.2 推送后创建了新 Change而不是更新旧 Change问题修改代码后git commit --amend并推送结果 Gerrit 上出现了一个全新的 Change旧的 Change 仍然存在。原因提交信息中的Change-Id 丢失或改变了。解决确保钩子已安装检查.git/hooks/commit-msg文件是否存在且可执行。检查提交信息git log --oneline -1查看最新提交确认末尾有Change-Id: Ixxx...。修复方法找到旧 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时提示冲突。解决流程不要慌。冲突是多人协作的常态。执行git status查看哪些文件冲突。打开冲突文件你会看到标记。这是 Git 标记的冲突区块你需要手动编辑文件保留你想要的内容删除这些标记。解决完所有冲突文件后使用git add file标记每个冲突已解决的文件。如果是 rebase 过程执行git rebase --continue。如果是 merge 过程执行git commit会弹出预填的合并信息。强烈建议在解决冲突后运行一遍项目测试确保你的修改没有破坏任何功能。5.4 Gerrit 页面显示 “Missing Change-Id in commit message”问题推送后Gerrit Change 页面报错无法识别提交。原因提交信息中没有 Change-Id钩子可能未生效。解决对于已推送的提交在本地使用git commit --amend手动添加正确的 Change-Id从错误信息或旧 Change 页面获取然后强制推送。对于未来的提交彻底检查并安装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 引用。在 Gerrit Change 页面找到对应的 Patch Set 编号如 PS2。在页面右侧或下载区域找到Download下拉菜单选择Checkout或Pull指令。你会看到类似git fetch ssh://... refs/changes/XX/123456/2 git checkout FETCH_HEAD的命令。复制并在你的仓库目录下执行即可将那个特定的补丁集拉取到本地并切换到该状态。下表总结了一些常见问题的快速应对策略问题现象可能原因快速排查步骤解决方案推送被拒绝[remote rejected]权限不足或推送到受保护分支1. 检查 SSH 密钥连接2. 确认推送引用为refs/for/添加正确公钥使用refs/for/branch创建了新 Change 而非更新Change-Id 丢失或不匹配git log -1查看提交信息末尾安装钩子git commit --amend修正 Change-Id 后强制推送变基/合并冲突多人修改同一文件git status查看冲突文件手动解决冲突git add后继续操作Web 页面报 Missing Change-Id提交信息无 Change-Id检查.git/hooks/commit-msg安装钩子或手动添加 Change-Id 后强制推送拉取代码后本地修改被覆盖误操作git pull导致合并查看git reflog寻找之前提交使用git reflog和git reset回退到之前状态掌握 Git 是开发者的基本功而理解 Gerrit 则是融入现代、严谨的协作开发文化的钥匙。这套组合的核心思想是用 Git 赋予个体开发的灵活与自由用 Gerrit 保障团队交付的质量与秩序。刚开始接触时可能会觉得流程繁琐但一旦习惯你会发现自己提交的代码质量更高团队协作也更顺畅。最重要的实操习惯就是勤变基、写清晰的提交信息、用好钩子、仔细看审查评论。剩下的就是在一次次提交、审查、迭代中积累经验了。