企业官网建设流程全解析

gh-stack rebase深度解析：--onto重放逻辑与级联更新源码导读

【免费下载链接】gh-stackGitHub Stacked PRs项目地址: https://gitcode.com/GitHub_Trending/ghst/gh-stack

📖gh-stack 是 GitHub 官方推出的 Stacked PRs（堆叠 PR）命令行工具，而它的rebase命令负责把整条分支栈像多米诺骨牌一样逐级刷新到最新基线。本文带你做代码级分析：gh-stack rebase是如何用git rebase --onto三个参数形式精确"重放"每个分支的独有提交、如何在底层 PR 被合并后自动切换 --onto 模式、以及冲突状态如何保存与续跑——一次读懂 squash/rebase 式堆叠更新的完整链路。

一、--onto 参数 30 秒看懂：重放的"起点"由谁指定

先明确一个前提：普通 rebase 与 --onto 重放的区别，在于"哪些提交要被重放"由谁说了算。

一句话记住三参数语义：

从<branch>上切下<oldBase>之后的所有提交，重新播放到<newBase>顶端。

这正是 gh-stack 的核心重放原语。它的落地代码只有寥寥数行，位于 internal/git/gitops.go：

func (d *defaultOps) RebaseOnto(newBase, oldBase, branch string, opts RebaseOpts) error { args := []string{"rebase"} if opts.CommitterDateIsAuthorDate { args = append(args, "--committer-date-is-author-date") } args = append(args, "--onto", newBase, oldBase, branch) err := runSilent(args...) if err == nil { return nil } return tryAutoResolveRebase(err, opts) }

两个值得注意的细节：

• --committer-date-is-author-date（CLI 上暴露为--preserve-dates别名）：重放会生成新 SHA、刷新 committer date，加上它可让提交时间保持"稳定"，减少 diff 时间线抖动；
• 失败后不是直接把错误抛出去，而是先进入tryAutoResolveRebase（第五节细讲）。

二、为什么堆叠 PR 必须靠 --onto：合并 PR 是最大的坑

这是全文最关键的一个场景。假设你的栈长这样：

┌── branch3 (PR #3，未合并) ┌── branch2 (PR #2，未合并) ┌── branch1 (PR #1，✅ 已合并进 main) main (trunk)

branch2 的提交历史里包含了 branch1 的提交（因为它叠在 branch1 之上）。现在 branch1 已合并进 main，你想把 branch2 刷新到最新 main——如果直接git rebase main，git 用 merge-base 判断重放范围，已合并进 main 的 branch1 提交可能被重复重放，产生幽灵提交甚至冲突。

gh-stack 的解法是：跳过已合并分支，并让它把"重放起点"传递给上层分支。这段逻辑在 internal/git/git.go 的RebaseOnto注释里被一语道破：

"This replays commits after oldBase from branch onto newBase. It is used when a prior branch was merged and the normal rebase cannot detect which commits have already been applied."

（当一个下层分支已合并时，普通 rebase 无法识别哪些提交已经应用，此时必须用 --onto。）

下面看级联循环里具体怎么做的。

三、cascadeRebase 源码导读：一次循环、三种命运

整个栈的刷新由 cmd/utils.go 的cascadeRebase驱动，从 trunk 方向逐层向栈顶推进。每个分支在循环里只有三种命运：

1️⃣ 已合并 → 跳过，但设置"重放起点"

if br.IsSkipped() { if br.IsMerged() { // 已合并PR的提交已在trunk里，上层必须用 // --onto 跳过它 ontoOldBase = originalRefs[br.Branch] needsOnto = true cfg.Successf("Skipping %s (PR %s merged)", ...) } else { // 排队中（queued）的PR被冻结在合并队列里， // 提交尚未进trunk，上层必须继续叠在它上面， // 因此不能切 --onto，反而要重置状态 needsOnto = false cfg.Successf("Skipping %s (PR %s queued)", ...) } continue }

originalRefs是 rebase 开始前对每个分支原始 SHA的快照（见 cmd/rebase.go 中resolveOriginalRefs(s)的调用）。把它记为ontoOldBase，含义是："这个分支重放前的原始顶点，就是上层分支重放时该剪掉的旧基线"。

⚠️ 注意queued（排队合并中）分支与merged的微妙差异：queued 的提交还没进 trunk，上层必须继续压在它上面，所以代码特意把needsOnto重置为false，避免误删这些"即将落地"的提交。

2️⃣ 上层分支 → 用 --onto 剪掉已合并部分

当needsOnto为真时，先向上找到"第一个未合并的祖先"作为落点，再处理一个边界情况——旧基线过期：

// 找 --onto 落点：第一个非 merged 祖先，找不到则用 trunk newBase := s.Trunk.Branch for j := absIdx - 1; j >= 0; j-- { if !s.Branches[j].IsMerged() { newBase = s.Branches[j].Branch break } } // 若 ontoOldBase 已不是该分支祖先（说明它已被 // 重放到更后面），回退用 merge-base，避免重复 // 重放已应用的提交 actualOldBase := ontoOldBase if isAnc, err := git.IsAncestor(ontoOldBase, br.Branch); err == nil && !isAnc { if mb, err := git.MergeBase(newBase, br.Branch); err == nil { actualOldBase = mb } } if err := git.RebaseOnto(newBase, actualOldBase, br.Branch, rebaseOpts); err != nil { return cascadeRebaseResult{Conflicted: true, ...} }

这段"过期检测 + merge-base 兜底"是防止重复重放的第二道保险：如果记录在案的老基线因为某些操作已不在当前分支历史里，就改用merge-base(newBase, branch)重新计算剪断点。

3️⃣ 常规相邻两层 → 记录"重放前"SHA 精确裁剪

没有 merged 分支干扰的常规情况，代码同样走 --onto，但 oldBase 用的是上一层分支重放前的原始 SHA：

if absIdx > 0 { rebaseErr = git.RebaseOnto(base, originalRefs[base], br.Branch, rebaseOpts) } else { // 栈底第一个分支：先 checkout，直接 rebase 到 trunk git.CheckoutBranch(br.Branch) rebaseErr = git.Rebase(base, rebaseOpts) }

为什么不用简单的git rebase base？因为上一层分支在本轮循环中刚被重放过——它的新 SHA 已经换过。若以新 tip 的 merge-base 来算范围，可能把上一层的提交误算进来。用originalRefs[base]（重放前的旧 tip）作 oldBase，就能只重放本分支独有的提交，边界干净利落。

💥 冲突：原地存档，续跑交状态

任一层重放冲突，循环立即停止并返回结构化结果（冲突分支索引、剩余队列、当前 onto 状态），runRebase随即把它序列化进.git/gh-stack-rebase-state（cmd/rebase.go 的rebaseState结构体）：

Rebasing feat/api onto feat/auth — conflict Conflicted files: C api/routes.go (lines 12–18) Resolve conflicts on feat/api, then run `gh stack rebase --continue` Or abort this operation with `gh stack rebase --abort`

--continue时，cmd/rebase.go 的continueRebase会：先git rebase --continue完成当前层，再校验剩余分支在栈中仍连续且顺序未变（栈中途被改动会明确报错并建议 abort），然后带着保存的NeedsOnto/OntoOldBase状态递归调用同一个cascadeRebase继续重放——这就是"级联"二字的完整含义。--abort则依据OriginalRefs快照把每个分支checkout + reset --hard回原样（cmd/rebase.go），做到无损回滚。

四、rerere 小抄：tryAutoResolveRebase 自动续跑

还记得RebaseOnto失败后先走进的tryAutoResolveRebase吗？它藏在 internal/git/git.go：

func tryAutoResolveRebase(originalErr error, opts RebaseOpts) error { for i := 0; i < 1000; i++ { if !IsRebaseInProgress() { return nil } conflicts, err := ConflictedFiles() ... if len(conflicts) > 0 { return originalErr // 还有冲突，交给人 } // rerere 自动解决了冲突 —— 自动 continue if rebaseContinueOnce(opts) == nil { return nil } } return originalErr }

机制是：开启 git rerere 后，历史冲突的解法会被复用并自动落盘。rebase 失败后，这里检查是否还有未解决冲突——若全部被 rerere 自动处理，就自动rebase --continue，多提交分支则循环续跑（上限 1000 次）。结果就是：对"上次这样解过"的冲突，gh stack rebase常常全程无人值守直接跑完。这也是 cmd/rebase.go 在 rebase 前调用ensureRerere(cfg)主动提示开启 rerere 的原因。

五、modify 的 fold-up：同一套 --onto 重放逻辑的复用

gh stack modify的交互式 TUI（上图）里可以删除、折叠、插入、重排分支。它的级联重放与rebase命令共用同一套 --onto 思想，核心在 internal/modify/apply.go：

• 执行前先记录每个分支"父层原始 tip SHA"到originalParentTips，重放时同样以它为 oldBase 精确裁剪；
• fold-up（向上折叠）尤其巧妙：被折叠分支 A 的提交本来就包含在上层目标分支 B 的历史里，无需 cherry-pick，只需把 B 的重放起点前移到 A 的父层——internal/modify/apply.go 一行originalParentTips[targetBranch] = originalParentTips[foldBranch]，随后git rebase --onto就会把"A 的提交 + B 自己的提交"一起重放，两个分支就此合一；
• 冲突恢复同样基于快照：状态文件记录RemainingBranches与OriginalRefs，gh stack modify --continue逐层续放，--abort调用Unwind依据 rebase 前的完整 SHA 快照还原所有分支（internal/modify/apply.go）。

六、关键文件清单：跟着这份地图读源码

结语

gh-stack 的 rebase 之所以敢对一整个堆叠 PR 栈做"手术"，靠的正是三个环环相扣的设计：原始 SHA 快照决定重放起点、--onto 三参数精确剪掉已合并部分、状态文件 + 快照回滚保证冲突可续跑、可撤销。看懂cascadeRebase里那个needsOnto标志的来龙去脉，你就读懂了堆叠 PR 工具的心脏。想要动手验证？clone 仓库后用 docs/src/content/docs/getting-started/quick-start.md 快速上手，再配合本文的文件清单逐层拆解即可。

【免费下载链接】gh-stackGitHub Stacked PRs项目地址: https://gitcode.com/GitHub_Trending/ghst/gh-stack