快速开始 / TSENGCHEN BLOG

SDK-Git-Workflow

08_QuickStart · 第 13 / 13 篇

Rockchip SDK 长期 Git 工作流

本文用于长期维护多仓库 Rockchip SDK。目标是在不复制整套源码的前提下,让 device/rockchip、u-boot、kernel-6.1、buildroot 始终有明确的干净基线;每个项目在独立分支开发、验证和上传 Gerrit。

[toc]

1. 核心原则

一个仓库只保留一个正式工作目录,不为每次提交创建新的源码副本。正式工作目录中有两类分支:

  1. *-clean:跟踪远程基线,只用于同步和创建项目分支,不直接开发。
  2. 项目分支:只存放一个项目,或一个可以独立构建、审核和回退的功能。

开始新任务前,先确认当前项目分支没有未提交改动;结束任务后切回 *-clean。不要在一个分支中叠加 UART、显示、客户板、内存裁剪等不相关任务。

2. SDK 仓库与干净基线

以下为本 SDK 的长期目录和基线分支约定:

仓库正式工作目录远程基线本地干净分支
Device/home/user/workspace/RK3588/device/rockchiprk/mastermaster-clean
U-Boot/home/user/workspace/RK3588/u-bootrk/next-devnext-dev-clean
Kernel 6.1/home/user/workspace/RK3588/kernel-6.1origin/develop-6.1develop-6.1-clean
Buildroot/home/user/workspace/RK3588/buildrootrk/mastermaster-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. 项目暂停、完成与切换

项目分支有未提交改动时,不直接切换到另一个项目。先完成以下三种处理中的一种:

  1. 完整功能:提交并上传 Gerrit。
  2. 临时保存:创建本地 WIP commit,并在提交说明中明确 WIP;不要上传。
  3. 不再需要:确认文件和范围后再显式删除。

完成或暂停后回到干净基线:

# 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. 禁止事项

  1. 不在不清楚分支基线时直接 git push HEAD。
  2. 不在脏工作区使用 git add .、git add -A。
  3. 不把 .img、.bin、日志、下载缓存、output/ 产物纳入源码提交。
  4. 不把多仓库修改压成一个提交或一次 push。
  5. 不在未检查影响范围时执行 git reset --hard、git clean -fd。
  6. 不认为切换 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 修改可追踪、可审核、可回退。

08_QuickStart · 文档目录
上一篇RK3xxx-SDK-Target-Switch-and-Config-Guide