Building an automated release branch sync tool with Bash

使用 Bash 制作一个 release 分支自动同步工具

前言

在日常开发维护中,我注意到一个反复出现却又容易被低估的痛点:从主干分支切出 release 分支后,接下来一到两周内,每个合入主干的 hotfix 都必须被 cherry-pick 到 release 分支。这件事说起来简单,执行起来却很麻烦,而且容易出现人为疏漏:忘记拣选、重复拣选、顺序错误,任何一个都会让 release 分支处于不一致的状态。

现有的工具通常与特定平台(GitHub、GitLab)的 API 绑定。这意味着你的自动化流程依赖某个平台的特定功能,而且迁移到其他平台时就需要重新构建。

这篇文章记录了我如何从零构建一个纯 Bash 的 git release 回移工具 —— pickle🔗。它只依赖 git,没有平台依赖,没有配置文件,没有状态文件,只有一个脚本文件。

了解问题

release 自动化可能会遇到什么困难?

  1. 选择哪些 commit? 不是主干上的所有 commit 都应该回移到 release 分支,通常只有 hotfix,但如何判断一个 commit 是不是 hotfix?
  2. 如何避免重复? 自动调度可能一天运行数次,同一个 commit 不能被拣选两次。但 cherry-pick 会生成新的 SHA、不同的 commit message,如何识别「这个 patch 已经在 release 分支上了」?
  3. 冲突处理? 两个分支各自演进后,patch 可能无法无冲突地应用。
  4. 顺序重要? 如果 fix #4 依赖 fix #2,跳过 #2 直接应用 #4,会得到一个能编译但行为错误的 release。
工具问题
GitHub backport bot🔗只在 GitHub 上运行;需要 label 触发;会创建 PR(而非直接 push)
release-please🔗专注于版本管理和变更日志,而非 hotfix 回移
自定义 shell 脚本每个团队各写一个,质量参差不齐,无法复用

设计决策

核心理念:只自动化 git 操作

pickle 只依赖 git 命令,不使用任何平台的 API。这意味着:

  • 同一条命令在 GitHub Actions、GitLab CI、Jenkins、Drone 或本地笔记本电脑上都能运行
  • 迁移 CI 平台不需要修改任何代码
  • 没有复杂的授权或平台带来的问题
  • 一个文件就可以部署:curl ... -o /usr/local/bin/pickle && chmod +x

配置方式:命令行 flag + 环境变量

不使用配置文件,配置已经存在于纳入版本控制的 CI YAML 中。每个 flag 都支持对应的 PICKLE_ 前缀环境变量,因为在 CI matrix 中设置环境变量比构造命令行参数更容易。优先级:flag > 环境变量 > 默认值。

选择规则:Conventional Commit🔗 优先

基于业界常用标准 Conventional Commit 的类型,只选择 fix,开发者不需要遵守任何额外规范,commit 的元数据已经在标题里了。

Terminal window
# 默认只选择 fix commits
pickle sync --target release/1.2 --from main
# 也可以自定义
pickle sync --target release/1.2 --types fix,perf
pickle sync --target release/1.2 --include '^\[HOTFIX\]' --exclude 'WIP'
# 或者完全自定义:用任意 git log 命令作为选择规则
git log --format=%H --grep=URGENT --author=oncall main \
| pickle pick --target release/1.2 -

冲突处理:停止运行,人工介入

  • 保留已经成功应用并推送的 commit
  • 中止发生冲突的 cherry-pick
  • 返回非零退出码,让 CI 失败
  • 输出可直接复制粘贴的解决命令

实际 CI 输出

以下是一次真实的 pickle sync 遇到冲突时的完整输出。主干上有三个 commit,中间那个与 release 分支的修改发生冲突:

Terminal window
pickle main → release/1.2
6903689c fix(A): 无冲突修复一 → 已拣选
6d52e8c8 fix(B): 有冲突的修复 → 冲突 — 需要人工介入
fc323f83 fix(C): 无冲突修复二 → 未尝试(运行已在上方停止)
1 个已拣选,0 个已跳过,1 个发生冲突,1 个未尝试
已将 release/1.2 推送到 origin
✗ 拣选 6d52e8c8 时发生冲突 fix(B): 有冲突的修复
c.txt
分支保持干净;未推送任何只应用了一部分的修改。
在本地解决:
git fetch origin
git switch release/1.2
git cherry-pick -x 6d52e8c8
# 修复冲突,然后执行:
git add -A && git cherry-pick --continue
git push origin release/1.2
保留 -x flag:它会记录 commit 的来源,以便
下次运行时知道不必再次尝试。
  • fix(A) 没有冲突,仍会推送到 release
  • fix(C) 显示「未尝试」,表示前面还有问题需要先解决
  • 直接列出冲突文件名
  • 退出码为 1,CI 亮红灯失败时提醒人工介入

解决流程

人工复制粘贴命令后会发生什么:

Terminal window
# 1. 切换到 release 分支并拣选发生冲突的 commit
git switch release/1.2
git cherry-pick -x 6d52e8c8
# → 冲突(内容):c.txt 中存在合并冲突
# 2. 手动解决冲突(编辑 c.txt,选择要保留的内容)
vim c.txt
# 3. 标记为已解决并继续
git add -A && git cherry-pick --continue
# → 完成,-x 尾注自动保留在 message 中
# 4. 推送
git push origin release/1.2

推送后,commit message 中会有这行尾注:

fix(B): 有冲突的修复
(cherry picked from commit 6d52e8c8)

下次运行 pickle sync 时,第二层去重机制就会识别出这个 commit 已经在 release 分支上,直接跳过:

Terminal window
$ pickle sync --target release/1.2 --from main
fc323f83 fix(C): 无冲突修复二 → 已拣选
6d52e8c8 fix(B): 有冲突的修复 → 跳过(已手动回移,包含 -x 尾注)
1 个已拣选,1 个已跳过
已将 release/1.2 推送到 origin

不需要记住任何规则——所需命令会在冲突发生时直接输出,而 -x 尾注确保解决后的 commit 不会被重复拣选。

冲突处理:如何避免重复拣选

这是整个工具最关键的部分,因为 sync 可能会对同一个分支运行数百次。pickle 使用三层去重机制:

第一层:patch-id

git patch-id 会根据 commit 的 diff 计算标识符,并对空白和行号进行规范化。因此,即使 cherry-pick 后生成了新的 commit SHA,或修改了 commit message、author、date,只要实际变更相同,通常仍会得到相同的 patch-id。

pickle 会自行构建 patch-id 集合,判断哪些变更已经存在于目标分支,而不是直接使用 git cherry。这是因为除了要比对普通 commit,还需要处理 merge commit:以第一个 parent 为基准,提取 git cherry-pick -m 1 对应的变更。同时,自行计算也能让 pickle 明确控制 commit 的遍历顺序。

首先,获取目标分支自共同祖先以来的 patch-id:

Terminal window
base=$(git merge-base "$FROM" "$TARGET")
git log -p --no-merges --no-renames --format='commit %H' "$base..$TARGET" \
| git patch-id --stable

接着,计算单个候选 commit 的 patch-id:

Terminal window
git diff-tree -p -m --first-parent --no-commit-id --no-renames --root "$sha" \
| git patch-id --stable

有了目标分支的 patch-id 集合后,pickle 会按照拓扑顺序,从旧到新检查候选 commit:

Terminal window
git rev-list --reverse --topo-order --no-merges "$TARGET..$FROM"

每个候选 commit 都会与集合进行比对。如果 patch-id 已存在,说明相同的变更已经出现在目标分支,可以直接跳过;否则才需要进入后续处理。

第二层:-x 尾注

Patch-id 唯一遗漏的情况:有人解决了冲突,因此应用后的 diff 与原始 diff 不同。

git cherry-pick -x 会在 message 中记录 (cherry picked from commit ...)。pickle 扫描 release 分支上的这一尾注来识别:

Terminal window
base=$(git merge-base "$FROM" "$TARGET")
git log --format=%B "$base..$TARGET" \
| sed -n 's/^[[:space:]]*(cherry picked from commit \([0-9a-f]\{7,40\}\)).*/\1/p'

第三层:pickle skip

如果决定不将某个 hotfix 发布到 release(例如它依赖 release 中没有的功能),上面两个信号都不会触发。pickle skip 会写入一个带尾注的空 commit:

Terminal window
pickle skip --target release/1.2 abc1234 --reason "依赖 1.2 中不存在的功能"

这会在历史中留下可审计的记录,表明「有人明确做出了这个决定」。

Agent Skill

可以通过 skills/pickle/ 使用 pickle。这个 skill 会教会 agent:

  • 命令和退出码的含义
  • 优先使用 --dry-run 的习惯
  • 如何解决冲突而不丢失 -x 尾注
Terminal window
npx skills add riceball-tw/pickle # 任意 agent:Claude Code、Cursor…
cp -r skills/pickle ~/.claude/skills/ # 或者直接复制过去

Claude Code 也可以通过插件形式安装:/plugin marketplace add riceball-tw/pickle。

延伸阅读