快速开始 / TSENGCHEN BLOG

Gerrit-Usage-Guide

08_QuickStart · 第 3 / 13 篇

Gerrit 使用教程

本文说明如何在 Rockchip 多仓库 SDK 中创建、上传、更新和检查 Gerrit Change。示例使用 RK3562 SPI NAND 适配场景,但方法适用于其他 SDK 改动。

[toc]

1. 基本概念

Git 的 commit 只保存在本地仓库。推送到 refs/for/<branch> 后,Gerrit 会创建一个 Change,供 Jenkins 和评审人员检查。Change 通过并合入目标分支后,代码才会成为远端正式分支的一部分。

常用对象如下:

名称作用
Commit本地一次完整修改记录。
ChangeGerrit 中对应一次待评审提交。
Patch Set同一 Change 的新版本。修改后重新上传会创建新的 Patch Set。
Change-Id用于将新的本地 commit 关联到已有 Gerrit Change 的标识。
refs/for/<branch>Gerrit 评审上传目标,而不是正式分支。

2. 上传前准备

2.1 确认远端和目标分支

在每个 Git 仓库中分别确认远端和分支。多仓库 SDK 的 Device、U-Boot、Kernel、Buildroot 是独立仓库,必须分别上传。

git remote -v
git branch --show-current
git log --oneline -3

SDK 的 manifest 中通常会声明项目的 dest-branch。以本次 RK3562 适配为例:

仓库Gerrit 目标分支
device/rockchipmaster
u-bootnext-dev
kernel-6.1develop-6.1
buildrootrockchip/2024.02

不要凭当前本地分支名称猜测 Gerrit 目标分支。SDK 常处于 detached HEAD 状态,这在 repo 管理的工作区中是正常现象。

2.2 检查改动范围

先查看全部本地状态,再只暂存本次需要上传的文件。

git status --short
git diff

不要在包含其他开发任务的工作区执行以下命令:

git add -A
git add .

应显式列出文件。例如 U-Boot 的 RK3562 SPI NAND 支持:

git add \
  configs/rk3562-spi-nand.config \
  arch/arm/dts/rk3562-evb2-ddr4-v10-spi-nand.dts

暂存后检查提交内容和格式:

git diff --cached --name-status
git diff --cached --check

git diff --cached --check 没有输出即表示未发现空白符、行尾等格式问题。

3. 创建本地提交

使用清楚、简短的提交标题。-s 会添加 Signed-off-by,适用于需要 DCO 签署的仓库。

git commit -s -m "rk3562: evb2: add spi nand boot support"

提交后检查:

git show --stat --oneline HEAD
git show --format=fuller --no-patch HEAD

确认提交信息中包含 Change-Id:。通常 commit-msg hook 会自动生成它。没有 Change-Id 时,后续重新上传会被 Gerrit 识别为新的 Change,而非原 Change 的新 Patch Set。

4. 上传新的 Gerrit Change

使用远端名 rk 和 refs/for/<branch> 上传。下面的命令只上传当前 HEAD 及其未在目标分支中的提交。

4.1 Device

git -C /home/user/workspace/RK3588/device/rockchip \
  push rk HEAD:refs/for/master

4.2 U-Boot

git -C /home/user/workspace/RK3588/u-boot \
  push rk HEAD:refs/for/next-dev

4.3 Kernel

git -C /home/user/workspace/RK3588/kernel-rk3562-spi-nand \
  push rk HEAD:refs/for/develop-6.1

4.4 Buildroot

git -C /home/user/workspace/RK3588/buildroot \
  push rk HEAD:refs/for/rockchip/2024.02

不同仓库不能合并为一次 Git push。可以依次执行多条命令,但 Gerrit 会创建各自独立的 Change。

上传成功时,终端会显示 Gerrit Change 链接,例如:

remote: SUCCESS
remote: https://<gerrit>/c/<project>/+/<change-number>

5. 更新已有 Change

当 Jenkins 或 reviewer 提出修改后,不要重新创建普通 commit。应修改原文件、暂存并使用 --amend 更新原提交。

git add arch/arm/dts/rk3562-evb2-ddr4-v10-spi-nand.dts
git diff --cached --check
git commit --amend --no-edit
git push rk HEAD:refs/for/next-dev

最后一次 push 会创建同一 Change 的新 Patch Set。旧的 Jenkins Verified 结果会自动失效,Jenkins 将针对新 Patch Set 重新检查。

6. 多任务工作区的安全做法

原 Kernel 工作区可能同时有其他芯片或功能的改动。不能直接从该目录上传一个依赖无关本地提交的 HEAD,否则 Gerrit 会收到一串无关 Change。

使用独立 worktree 从目标分支创建干净工作区,再只摘取目标提交:

cd /home/user/workspace/RK3588/kernel

git worktree add -b rk3562-spi-nand-clean \
  /home/user/workspace/RK3588/kernel-rk3562-spi-nand \
  rk/develop-6.1

git -C /home/user/workspace/RK3588/kernel-rk3562-spi-nand \
  cherry-pick <rk3562-spi-nand-commit>

上传前确认该 worktree 只包含预期文件:

git -C /home/user/workspace/RK3588/kernel-rk3562-spi-nand status --short
git -C /home/user/workspace/RK3588/kernel-rk3562-spi-nand \
  diff --name-only rk/develop-6.1..HEAD

不要为清理工作区随意执行 git reset --hard、git checkout -- 或删除目录。这些操作可能丢失其他任务的未提交修改。

7. Gerrit 页面状态说明

Gerrit Dashboard 中常见字段如下:

页面内容含义
Outgoing reviews当前账号发起、等待评审的 Change。
Your turn当前需要作者或评审者关注的 Change。
2 missing还有两个提交条件未满足,常见为 Code-Review 和 Verified。
CRCode-Review 评审标签。
VVerified 标签,通常由 Jenkins 构建或检查任务设置。
Verified -1自动检查失败,需要查看 Jenkins 日志并修复后上传新 Patch Set。
NEWChange 已创建,尚未合入。

例如新增 DTS 时出现以下告警:

WARNING: Missing or malformed SPDX-License-Identifier tag in line 1
WARNING: Misplaced SPDX-License-Identifier tag - use line 1 instead

表示 SPDX 标签没有位于文件第一行。应使用:

// SPDX-License-Identifier: GPL-2.0+
/*
 * Copyright (c) 2026 Rockchip Electronics Co., Ltd.
 */

修改后按第 5 节创建新 Patch Set。

8. 常见上传问题

8.1 no new changes

表示当前 HEAD 已经上传,且之后没有新的 commit。无需重复 push。

remote rejected: no new changes

确认是否修改过文件并执行了 git commit --amend。只有产生新 commit 后,Gerrit 才会创建新的 Patch Set。

8.2 unpacker error 或 Missing tree

若推送出现:

remote unpack failed: error Missing tree <object-id>

先确认本地提交范围和对象完整性:

git status --short
git diff --check
git fsck --full --no-dangling

当本地检查正常时,可以使用非 thin pack 重试,让 delta 基对象完整随推送包发送:

git push --no-thin rk HEAD:refs/for/develop-6.1

本次 Kernel 上传即通过该方法解决。

8.3 SSH 认证失败

SDK 常使用 SSH Gerrit 远端,例如:

ssh://<server>:29418/<project>

应使用已添加到 Gerrit 账户的 SSH 公钥认证,通常不需要输入 Gerrit 网页密码。可用以下命令验证账号连通性:

ssh -p 29418 <server> gerrit version

认证失败时,在 Gerrit 网页账户设置中检查 SSH Keys,或联系管理员开通权限。

8.4 大型二进制文件

字体、模型或固件二进制文件通常没有文本行数统计,Gerrit 中可能显示为 -。提交前应确认项目是否允许该文件大小和类型;建议将二进制文件单独提交,避免与代码配置改动混合。

9. 上传后的自检

在 Gerrit 页面确认以下内容:

  1. Project 和 Branch 正确。
  2. Files 页只包含本次修改的文件。
  3. Change-Id 与预期 Change 一致。
  4. 新 Patch Set 已触发 Jenkins。
  5. CR 和 V 标签均满足项目要求后再提交合入。

本地可再次检查每个提交相对目标分支的文件范围:

git diff --name-only rk/<target-branch>..HEAD
git diff --check rk/<target-branch>..HEAD

这样可以确保上传内容可追踪、可评审,并避免将其他开发任务误带入 Gerrit。

08_QuickStart · 文档目录
上一篇00-Quickstart-Index下一篇RK3506_RK3576_RS485_Quick_Start