Rockchip SDK 长期 Git 工作流
本文用于长期维护多仓库 Rockchip SDK。目标是在不复制整套源码的前提下,让 device/rockchip、u-boot、kernel-6.1、buildroot 始终有明确的干净基线;每个项目在独立分支开发、验证和上传 Gerrit。
[toc]
1. 核心原则
一个仓库只保留一个正式工作目录,不为每次提交创建新的源码副本。正式工作目录中有两类分支:
*-clean:跟踪远程基线,只用于同步和创建项目分支,不直接开发。- 项目分支:只存放一个项目,或一个可以独立构建、审核和回退的功能。
开始新任务前,先确认当前项目分支没有未提交改动;结束任务后切回 *-clean。不要在一个分支中叠加 UART、显示、客户板、内存裁剪等不相关任务。
2. SDK 仓库与干净基线
以下为本 SDK 的长期目录和基线分支约定:
| 仓库 | 正式工作目录 | 远程基线 | 本地干净分支 |
|---|---|---|---|
| Device | /home/user/workspace/RK3588/device/rockchip | rk/master | master-clean |
| U-Boot | /home/user/workspace/RK3588/u-boot | rk/next-dev | next-dev-clean |
| Kernel 6.1 | /home/user/workspace/RK3588/kernel-6.1 | origin/develop-6.1 | develop-6.1-clean |
| Buildroot | /home/user/workspace/RK3588/buildroot | rk/master | master-clean |
远程名和目标分支必须以当前仓库实际配置和 manifest 为准。开始新项目时可检查:
cd /home/user/workspace/RK3588
git -C device/rockchip remote -v
git -C u-boot remote -v
git -C kernel-6.1 remote -v
git -C buildroot remote -v
3. 开始新项目
以下示例为 Kernel 6.1 新建项目分支,项目名使用小写字母、数字和连字符。其他仓库只需替换目录、远程名和基线分支。
cd /home/user/workspace/RK3588/kernel-6.1
git status --short
git switch develop-6.1-clean
git fetch origin develop-6.1
git rebase origin/develop-6.1
git switch -c <project>-<feature>
每条命令的作用如下:
| 命令 | 作用 | 预期结果 |
|---|---|---|
git status --short | 检查当前工作区 | 无输出才可切换或同步。 |
git switch develop-6.1-clean | 回到干净基线 | 该分支不保留功能修改。 |
git fetch origin develop-6.1 | 获取远程最新提交 | 只更新本地远程引用,不改工作区。 |
git rebase origin/develop-6.1 | 更新本地干净基线 | develop-6.1-clean 与远程基线对齐。 |
git switch -c <project>-<feature> | 创建项目分支 | 新分支从最新干净基线开始。 |
Device、U-Boot、Buildroot 的新项目命令分别为:
# Device
cd /home/user/workspace/RK3588/device/rockchip
git status --short
git switch master-clean
git fetch rk master
git rebase rk/master
git switch -c <project>-<feature>
# U-Boot
cd /home/user/workspace/RK3588/u-boot
git status --short
git switch next-dev-clean
git fetch rk next-dev
git rebase rk/next-dev
git switch -c <project>-<feature>
# Buildroot
cd /home/user/workspace/RK3588/buildroot
git status --short
git switch master-clean
git fetch rk master
git rebase rk/master
git switch -c <project>-<feature>
如果 git status --short 有输出,先识别文件归属。不要为了开始新任务而直接执行 git reset --hard 或 git clean -fd;这些命令会删除当前项目未提交的内容。
4. 日常开发与自检
修改前、修改中和提交前都检查当前分支和差异:
git branch --show-current
git status --short
git diff
git diff --check
git diff --check 无输出表示未发现行尾空格等格式问题。新文件还应检查路径、文件头和构建入口,例如新增 DTS 时确认 SPDX、版权、DTS Makefile;新增 kernel fragment 时确认 Device defconfig 中有对应 RK_KERNEL_CFG_FRAGMENTS 引用。
5. 一项功能一个提交
一个提交必须能独立说明、构建和回退。跨仓库功能必须在每个仓库分别提交,不能将 Device、Kernel、Buildroot 合并为一个 Git commit 或一次 Gerrit Change。
暂存时只列出当前任务文件,禁止在共享 SDK 工作区使用 git add . 或 git add -A:
git add \
arch/arm/boot/dts/rk3506g-example.dts \
arch/arm/boot/dts/Makefile
git diff --cached --name-status
git diff --cached --check
git commit -s -m "ARM: dts: rockchip: rk3506g: add example board"
提交后立即确认实际文件范围:
git show --stat --oneline HEAD
git diff-tree --no-commit-id --name-status -r HEAD
git status --short
6. SDK 配置与分支切换
Git 分支只决定源码版本;SDK 当前构建目标还由 output/defconfig 决定。切换分支后,必须确认 selected defconfig,不能假设它会自动切换。
cd /home/user/workspace/RK3588
readlink -f output/defconfig
sed -n '1,80p' output/defconfig
以 RK3506 为例,Device defconfig 通过以下变量选择内核和 rootfs:
RK_BUILDROOT_BASE_CFG="..."
RK_KERNEL_CFG="rk3506_defconfig"
RK_KERNEL_CFG_FRAGMENTS="..."
RK_KERNEL_DTS_NAME="..."
切换到其他项目或基线固件时,先按 SDK 的 build.sh <chip>:<defconfig> 或 mk-config.sh 选择对应 defconfig,再开始构建。切换配置后若删除了 Buildroot 软件包,使用 clean-rootfs 后重建 rootfs,避免旧产物残留。
7. 上传 Gerrit 前的门禁
上传前必须从目标分支重新检查提交范围。Kernel 6.1 示例:
cd /home/user/workspace/RK3588/kernel-6.1
git fetch origin develop-6.1
git rebase origin/develop-6.1
git diff --check origin/develop-6.1..HEAD
git log --oneline origin/develop-6.1..HEAD
git diff --name-status origin/develop-6.1..HEAD
只有上述文件列表完全属于当前任务时,才上传:
git push origin HEAD:refs/for/develop-6.1
其他仓库的 Gerrit 上传命令:
# Device
git -C /home/user/workspace/RK3588/device/rockchip \
push rk HEAD:refs/for/master
# U-Boot
git -C /home/user/workspace/RK3588/u-boot \
push rk HEAD:refs/for/next-dev
# Buildroot
git -C /home/user/workspace/RK3588/buildroot \
push rk HEAD:refs/for/master
refs/for/<branch> 创建或更新 Gerrit 审核,不会直接写入远程正式分支。上传后保存终端输出的 Change 链接,并确认项目、目标分支、提交说明和文件列表。
8. 根据 Review 更新 Patch Set
reviewer 或 Jenkins 提出问题后,仍在原项目分支修改,不要新建不相关分支或新开普通提交。保持原 Change-Id,使用 --amend 更新提交:
git add <review-fixed-file>
git diff --cached --check
git commit --amend --no-edit
git push <remote> HEAD:refs/for/<target-branch>
如果提交说明本身需要修改:
git commit --amend
Gerrit 会为同一 Change 创建新的 Patch Set。旧 Patch Set 的 Jenkins Verified 结果会自动失效,必须等待新 Patch Set 重新验证。
9. 项目暂停、完成与切换
项目分支有未提交改动时,不直接切换到另一个项目。先完成以下三种处理中的一种:
- 完整功能:提交并上传 Gerrit。
- 临时保存:创建本地 WIP commit,并在提交说明中明确 WIP;不要上传。
- 不再需要:确认文件和范围后再显式删除。
完成或暂停后回到干净基线:
# Kernel 6.1
git -C /home/user/workspace/RK3588/kernel-6.1 switch develop-6.1-clean
# Device / Buildroot
git -C /home/user/workspace/RK3588/device/rockchip switch master-clean
git -C /home/user/workspace/RK3588/buildroot switch master-clean
# U-Boot
git -C /home/user/workspace/RK3588/u-boot switch next-dev-clean
切换完成后运行 git status --short。无输出表示该仓库可以安全开始下一项工作。
10. 已经混入无关提交时的处理
发现当前项目分支已经混入其他项目提交时,不要直接 push HEAD。先检查:
git log --oneline <remote>/<target-branch>..HEAD
git diff --name-status <remote>/<target-branch>..HEAD
若范围包含无关提交,最安全的短期补救是从远程基线创建一次性干净 worktree,只 cherry-pick 当前功能提交,再上传。该 worktree 是历史已经混乱时的应急隔离手段,不应作为日常开发模式。
git worktree add -b <project>-upload \
/home/user/workspace/<project>-upload \
<remote>/<target-branch>
git -C /home/user/workspace/<project>-upload cherry-pick <commit-id>
git -C /home/user/workspace/<project>-upload diff --check <remote>/<target-branch>..HEAD
上传成功并确认 Gerrit 文件范围后,删除临时 worktree 回收空间:
git worktree remove /home/user/workspace/<project>-upload
随后回到正式工作目录,重新以对应 *-clean 分支创建下一个项目分支。
11. 禁止事项
- 不在不清楚分支基线时直接
git push HEAD。 - 不在脏工作区使用
git add .、git add -A。 - 不把
.img、.bin、日志、下载缓存、output/产物纳入源码提交。 - 不把多仓库修改压成一个提交或一次 push。
- 不在未检查影响范围时执行
git reset --hard、git clean -fd。 - 不认为切换 Git 分支就等于切换 SDK 构建 defconfig。
12. 每日速查
# 进入某仓库后:确认状态
git branch --show-current
git status --short
# 查看本次修改
git diff
git diff --check
# 提交后确认
git show --stat --oneline HEAD
git status --short
# 回到干净基线前确认
git status --short
git switch <clean-branch>
长期保持“一个正式目录、一个干净基线分支、一个项目分支”的结构,可以在频繁切换芯片、客户板和功能时保持 SDK 修改可追踪、可审核、可回退。