在团队协作里最容易被当成小事忽略、最后却把人卡住的往往不是代码冲突而是一个看起来很基础的问题当前这个分支到底是不是某个 GitHub Stacked PR 的一部分这个疑问我经常遇到。比如你接手一个已经迭代了两周的开发分支Git 历史里全是feat: xxx、chore: yyyPR 列表里开着七八个看起来都有关联的 pull request你并不知道自己站在哪一环。又或者团队其他人问你“你那个分支是不是挂在刚才那组 stacked PR 下面如果第一个 PR 被合了后面几个要不要一起 rebase”你打开 GitHub 翻了几页最后只能靠猜。很多人会以为这是 Git 使用不熟练的问题多学几个命令就能解决。但真不是。Stacked PR 本身是 GitHub 工作流的一种特殊用法Git 只能确认提交之间的父子关系而“分支属于哪个 Stacked PR”是一个 PR 元数据问题。要可靠地判断必须换一套思路。1. Stacked PR 为什么会让“一个分支属于谁”变成难题1.1 先讲清楚 Stacked PR 到底是什么所谓 Stacked PR通常不是 GitHub 官方提供的一个独立功能而是一套通过分支依赖关系组织 PR 批次的工作流。普通 PR 的结构很简单feature分支直接对比mainPR 合并后 feature 分支进入 main。一次只处理一个改动。Stacked PR 则不同。一个大功能被拆成多个小功能每个小功能各自对应一个分支和 PR但这些 PR 并不是各自独立指向 main而是形成一条链PR #1: feat-base - mainPR #2: feat-2 - feat-basePR #3: feat-3 - feat-2也就是说后一个 PR 的 base 分支是前一个 PR 的 head 分支。最后一个 PR 的 base 才是 main。这样每个 PR 的 diff 只包含自己那部分改动reviewer 可以先 review 第一层再顺序往下看。只要第一层合入 main把后续分支 rebase 到新的 main 上链上后续 PR 的 diff 依然干净不会混入已经审查过的代码。这种做法的价值很明显。一个大产品功能往往涉及接口设计、核心逻辑、UI 呈现、测试补充如果全部塞进一个 PRreviewer 很难消化。拆成 Stacked PR 后每次 review 的差异都聚焦在一个最小单位审批速度会快很多。但代价也就在“链”这个字上。只要有链就有上下游关系就有“这个分支是不是属于某条链”的归属问题。1.2 为什么 GitHub 的普通 PR 流程没有专门回答这个问题如果你每天都在用普通 PR基本不会问“这个分支是不是属于某个 Stacked PR”。因为普通 PR 里分支归属很清晰分支指向 main就是一个独立 PR分支不指向 main那就还没准备好。不存在“链”的概念。Stacked PR 打破了这种清晰边界。分支不再只是“面向 main 的一个开发单元”它可能是链中间的一个环节也可能是链的开头还可能已经脱离了原来那条链。GitHub 的 PR 页面虽然会显示 base 分支和 head 分支但没有一个汇总视图告诉你“这条分支从属于哪一条依赖链”。默认只能看到一层一个 PR 的 base 是什么。你点进 base 分支对应的 PR又能看到它的 base 是什么这样一层层往上翻才能还原出完整的链。这个“逐层翻”的动作就是问题核心。Git 不会记录“PR 依赖关系”它只记录 commit 的父子关系和历史。你从git log里可以看到两个分支共享哪些提交但看不到“这个分支被哪个 PR 引用为 base”。所以要回答“我的分支是不是某个 Stacked PR 的一部分”本质上不是一个 Git 操作而是一个 PR 元数据查询。你需要查的是这个分支上有没有 PR这个 PR 的 base 是什么base 上有没有另一个 PR一路往上能不能走到默认分支。1.3 这个问题会在哪些场景变成真正的阻塞如果只是偶尔用一次 Stacked PR判断分支归属可能只是“确认一下”。但实际工作流里下面几个场景经常会被它卡住。第一个场景是多层 PR 的 rebase。链上的第一个 PR 合入 main 后后续 PR 的 base 分支往往需要 rebase 到新的 main 上。如果你手里有七八个分支又不知道哪些分支属于同一条链就很可能会漏掉某个依赖分支导致后续 CI 报一堆错误。第二个场景是 Review 之前的准备。你作为 reviewer 收到一个 PR发现 base 不是一个已合入的主分支而是一个看起来还在开发中的分支。这时你需要判断“这个 PR 是不是 stacked 链的一部分”才能决定自己应该只看这个 PR 的 diff还是需要连同 base 分支的改动一起理解。第三个场景是分支清理。项目上线后开发者会删除已经合入的分支。Stacked PR 链上如果中间某个 PR 被合并而下游 PR 还没合入直接删除 base 分支会导致下游 PR 的 base 引用变得不清晰。如果你能准确判断哪些分支还挂在链上就不会误删依赖。这几个场景说明判断分支归属不是一个“锦上添花”的小技巧而是维护 Stacked PR 工作流的基本能力。2. 别被分支名、提交历史和 GitHub UI 骗了2.1 分支名和 commit message 只能提供线索不能作为判断依据最容易想到的方法是看名字。很多团队在拆 Stacked PR 时会用feat/user/1、feat/user/2、feat/user/3这种带序号的分支名或者a/stack-xxx这样带前缀的命名。看到这种名字你确实能大概猜出分支之间的顺序。但分支名是写给人看的不是程序逻辑。GitHub 在计算 PR 依赖时完全不看分支名叫什么。你完全可以把feat/user/3分支的 base 设置成 main也可以把feat/user/1分支的 base 设置成另一个分支。只要有人手动改过 base分支名就失去意义。commit message 也一样。有人会在提交信息里写stacked on top of ...但这种信息不是结构化数据。一旦经过 rebasecommit message 可能会被改写而且无法被脚本稳定解析。如果你要根据 commit 信息来做自动化判断迟早会遇到一个没按约定写提交的开发。所以我的建议是分支名和 commit message 只能作为辅助观察永远不要作为最终结论。2.2git log和git merge-base只能说明“提交重叠”不能说明“PR 依赖”还有一种容易踩坑的做法是想通过 Git 历史来判断。比如你会git log --oneline --graph看到某个分支的提交历史里包含了另一个分支的 recent commit于是认为它们属于同一个 Stacked PR。这个推论在大多数情况下是正确的但不保证。Git 是一个提交图某个分支的提交历史里包含另一个分支的提交只表示它们之间存在祖先关系。这种关系可能来自 Stacked PR也可能来自一次简单的 merge甚至可能是一个长期维护分支从另一个 release 分支同步代码。仅凭 Git 历史你无法判断这两个分支是否被同一个 PR 链管理。git merge-base也只是找到两个分支的共同祖先它不能告诉你 PR 的 base 怎么设置。两个分支可能共享同一个祖先但一个是独立 PR另一个挂在 Stacked PR 链上。你能看到的只是历史有交集看不到 GitHub 上的 PR 依赖元数据。因此用纯 Git 命令判断 Stacked PR 归属方向就错了。2.3 GitHub UI 的默认视图也不够直观在 GitHub 上打开任意一个 PR页面会显示“base: main - head: feature”。你要是顺着 base 判断也能找到上游 PR。但 GitHub 的默认 UI 只展示当前 PR 这一层的 base它不会主动告诉你“这个 base 分支是另一个 PR 的 head”。如果你在某个 PR 页面看到 base 分支是一个非 main 分支你需要手动点击这个 base 分支名找到它对应的 PR再查看它的 base再继续点击。这种操作在链只有两三层时还能忍受一旦链上有五六个 PR逐层点击非常容易看漏而且页面状态会来回跳。还有一个更隐蔽的问题PR 是动态的。base 分支可以被修改你上一次看到的关系可能在下一次刷新后就不一样了。GitHub UI 适合作为人工确认的辅助工具不适合作为系统判断的唯一来源。3. 一个可靠的手动判断法沿 base 分支一层层向上查3.1 核心思路用 PR 的baseRefName和headRefName还原依赖链既然问题出在 PR 元数据上那么最可靠的方法就是直接读 PR 的元数据。在 GitHub 的 PR 结构里有两个关键字段headRefName当前这个 PR 对应的分支也就是改动所在的分支。baseRefName当前这个 PR 要合入的目标分支。对于一个普通 PRbaseRefName 通常是main、master、develop这类基础分支。但对于 Stacked PR 链上的 PR它的 baseRefName 往往是另一个分支的名字而且这个分支很可能就是另一个 PR 的 headRefName。所以判断“当前分支是否属于某个 Stacked PR”可以变成这样一个递归查询查当前分支是否有对应 PR。如果有看这个 PR 的 baseRefName 是什么。如果 baseRefName 不是默认分支再去查名为 baseRefName 的分支是否有对应 PR。重复这个过程直到 baseRefName 是默认分支或者找不到对应 PR。这个过程就是还原 Stacked PR 依赖链的过程。如果当前分支在链上最终会走到默认分支如果不在链上第一步就会发现它根本没有任何 PR或者它的 base 直接就是默认分支。3.2 用 GitHub CLI 手动查依赖链如果你的机器上安装了 GitHub CLIgh并且已经登录那手动判断非常快。先确认当前分支git branch --show-current假设当前分支是feat/stack-2然后用 gh 查看这个分支的 PRgh pr view feat/stack-2 --json number,baseRefName,headRefName,state,url输出大概是{ number: 123, baseRefName: feat/stack-1, headRefName: feat/stack-2, state: OPEN, url: https://github.com/your/repo/pull/123 }看到baseRefName是feat/stack-1说明这很可能不是最终 PR。继续查feat/stack-1:gh pr view feat/stack-1 --json number,baseRefName,headRefName,state,url如果feat/stack-1的baseRefName是main那链条就清楚了feat/stack-2 - feat/stack-1 - main当前分支属于一个长度为 2 的 Stacked PR 链。如果feat/stack-1也有自己的 base那就继续向上查。这套方法的好处是它不依赖分支名也不依赖 commit message只看 GitHub 上真实的 PR 元数据。只要 baseRefName 设置正确结论就是可靠的。3.3 三种典型结果以及每一种的含义手动查完之后通常会遇到三种情况。我列成表方便对比。当前分支对应的 PRPR 的 baseRefName结论有且状态 OPENmain 或默认分支独立 PR不属于任何 Stacked PR 链有且状态 OPEN另一个非默认分支而该分支也有 OPEN PR当前分支在某个 Stacked PR 链上有但状态合并/关闭另一个非默认分支需要进一步确认可能是链已被部分合入也可能是历史遗留第一种情况最简单直接回复“它就是一个独立 PR”。第二种情况就是 Stacked PR 链的一部分。第三种情况要小心因为链上可能已经有一部分 PR 合入 main剩下的 PR 还挂在旧分支上。这时候需要把向上递归的范围扩大把已合入 PR 也纳入查询。除了这三种情况还有一个边界当前分支根本没有 PR。这时不能直接说“不属于任何 Stacked PR”。你手上有代码但还没推送或者 PR 还没创建。GitHub 上没有 PR 元数据就无法判断。这种情况下应该先确认开发者意图再决定下一步。4. 把判断流程固化成脚本和团队约定4.1 为什么值得脚本化手动查依赖链虽然可靠但每查一个分支都要敲一遍gh pr view如果链很长效率并不高。更重要的是手动查询很容易在多个终端窗口之间遗漏。你刚查完 PR #123 的 base 是feat/stack-1切到另一个窗口去查看feat/stack-1的 PR再切回来时可能已经忘了前面几层的结构。把流程固化成脚本至少可以让每次判断有可复现的输出。我自己一般会先写一个最小脚本确保逻辑正确再逐步扩充。这里给你一个可以直接实验的 bash 示例结构#!/usr/bin/env bash set -euo pipefail DEFAULT_BRANCH${1:-main} current_branch$(git branch --show-current) branch$current_branch echo Current branch: $branch echo DEFAULT_BRANCH: $DEFAULT_BRANCH echo --- for ((i 0; i 10; i)); do # 查询当前分支对应的 open PR pr_json$(gh pr list --head $branch --json number,baseRefName,headRefName,state --limit 1 2/dev/null || true) if [[ -z $pr_json || $pr_json [] ]]; then echo No open PR found for branch: $branch break fi number$(echo $pr_json | jq -r .[0].number) base$(echo $pr_json | jq -r .[0].baseRefName) head$(echo $pr_json | jq -r .[0].headRefName) state$(echo $pr_json | jq -r .[0].state) echo PR #$number: $head - $base (state: $state) if [[ $base $DEFAULT_BRANCH ]]; then echo Found default branch base. End of chain. break fi branch$base done这段脚本的逻辑很简单从当前分支开始不断查询以当前分支为 head 的 open PR如果 PR 的 base 不是默认分支就把 base 当作下一个要查询的分支继续循环。为了防止意外死循环我加了10层深度限制。使用前需要有ghCLI、jq和 GitHub 登录授权。如果你没装jq也可以用 python 替代。脚本只是示例不是开箱即用的生产工具因为实际项目里可能还有 fork 场景、多仓库场景、草稿 PR 场景这些都需要单独处理。4.2 进阶脚本返回完整 PR 链而不是只告诉你“是不是”上面这个脚本只负责把链路打印出来严格说并没有直接回答“是不是 Stacked PR 的一部分”。如果想要一个更明确的判断结果可以把链路收集到一个数组里最后输出结论。Python 写起来会更清晰。伪码思路如下获取当前分支名。循环最多 10 次调用gh pr list --head branch --json number,baseRefName。如果查不到记录“无 PR”退出。如果查到多个 PR这种场景很少但可能出现优先取 state 为 OPEN 的那一个或者提示用户指定。把当前 PR 信息 append 到链列表。如果 base 是默认分支标记为“到达链顶”退出。否则将branch替换为base继续循环。输出链列表以及“当前分支是否处于 Stacked PR 链上”的结论。这个脚本可以在团队内分享。因为每个团队的默认分支不一样最好让默认分支作为参数传入或者通过gh repo view --json defaultBranchRef获取。4.3 再往前一步用团队约定减少“事后判断”的次数脚本能解决“我已经有了一个分支怎么判断它属于谁”的问题但不能解决“为什么会形成这种混乱”的问题。真正高效的做法是在源头上减少模糊性。一个比较实用的约定是Stacked PR 链里的每个 PR都应该在 PR 描述里写明它依赖哪个 PR以及它的 base 分支应该指向哪个分支。可以是手写也可以是 PR 模板里增加一个栏位。在这个基础上分支命名也建议统一。不一定非要带序号但至少要让别人一眼能看出“这个分支看起来不是直接面向 main 的”。比如统一使用stack/功能名/层级或者feat/用户/功能/序号。注意这只是辅助不是判断依据。如果团队使用的 Stacked PR 频率很高也可以考虑引入专门管理栈的 CLI 工具。社区里已经有一些工具用来自动创建依赖分支、自动修改 base、rebase 后批量更新链上 PR。不过引入新工具会带来学习成本和流程调整建议先在少量分支上试用确认它能和你们的 GitHub 工作流兼容再推广到团队。我把这个过程总结成一个可复用框架叫“三层判断法”看元数据用gh pr list --head branch确认这个分支有没有 PR。看 base看 PR 的 baseRefName 是不是默认分支。向上递归base 不是默认分支时继续查 base 分支的 PR。这个框架适用于所有基于 GitHub 的 Stacked PR 工作流。5. 真正落地时需要注意的边界与排查链路5.1 脚本和手动查询都可能被哪些因素干扰有时候你得到的结论和预期不符不一定是 Stacked PR 定义变了而是查询过程踩了一些边界。第一PR 状态。上面脚本默认查询 open 状态的 PR。如果当前分支的 PR 处于 draft 状态它仍然是 open能不能算 Stacked PR 的一部分严格来说只要它的 base 是另一个非默认分支它就是链上的一环和 draft 无关。但如果 PR 被关闭脚本就会返回“无 open PR”这时不能直接下结论因为历史链可能已经被拆掉。第二base 分支已经合入默认分支。假设 PR #1 已经合入 mainPR #2 的 base 还是feat/stack-1但feat/stack-1已经合入 main 后被删除了。这时查feat/stack-1可能查不到 open PR但 PR #2 其实仍然是一个悬空的 Stacked PR或者说是一个“曾经属于 Stacked PR、现在 base 过时的 PR”。判断时要看 base 分支是否等于默认分支而不是看 base 分支还存不存在。第三fork 仓库的 head 分支。如果开发者在 fork 仓库里工作gh pr list --head branch可能需要指定--head owner:branch或--repo owner/upstream否则查不到。第四权限问题。如果你没有目标仓库的读取权限gh CLI 和 GitHub API 都可能返回空结果。拿到“没有 PR”的结果时先检查一下登录状态和仓库权限别急着下判断。5.2 一个值得记住的排查链路当你发现判断结果不稳定时建议按下面这个顺序排查确认仓库和分支信息git remote -v、git branch --show-current、git fetch是否已经同步最新远端状态。确认 gh CLI 状态gh auth status是否已经登录、gh repo set-default是否指向正确仓库。确认 PR 查询条件gh pr list --head branch是否真的返回了你想要的那条 PR是否因为 PR 状态不是 open 而被过滤。确认 base 分支gh pr view number --json baseRefName是否能正确返回而不是因为 fork 或 remote 问题读到空值。如果手动步骤都对但结果仍然奇怪就用最原始的方式确认打开 PR 的 GitHub 页面看 base 下拉框看“Merge”按钮上方显示的 base 分支再对比脚本输出。最后这一步看似笨但在自动化结果和人脑判断冲突时它可以帮助你判断是脚本逻辑问题还是自己对 Stacked PR 的理解有偏差。5.3 这个判断方法适用于哪些场景不适用于哪些场景从工具角度看这套方法只适用于 GitHub 仓库。如果你用的是 GitLab、Gitea 或者其他 Git 托管平台“merge request” 和 “PR” 的元数据结构不一样不能直接套用。但只要了解对应平台的 base 分支和 source 分支概念思路是相通的。从团队规模看Stacked PR 更适合有一定协作经验、代码评审规范比较成熟的团队。如果你刚使用 GitHub 不久或者团队只有两三人我建议先老老实实走普通 PR 流程至少把 main 分支的稳定性维护好。Stacked PR 只是把一个大的 diff 分散到多个 PR 里并不会自动让代码变好。如果 review 习惯不好只是多了一堆互相依赖的 PR 需要照顾而已。还要注意Stacked PR 不是银弹。它适用于跨多个代码模块的大功能但不适用于所有改动。比如一个简单的 bug 修复拆成三层就完全没有必要。判断分支是否属于 Stacked PR 的能力是为了更好地掌握这种工作流而不是为了鼓励把所有改动都做成栈。注意不要因为脚本能自动判断就放弃人工 review 对 base 分支的确认。脚本只是把“当前分支是不是在栈上”这个问题回答得更快但“这个栈设置得合不合理”仍然需要人来判断。6. 回到最初的问题先确定你的工作流需要哪种答案如果回到文章开头那个问题“这个分支是不是某个 GitHub Stacked PR 的一部分”你会发现答案并不是非黑即白。有一种答案是“它现在属于这条链”这时你需要把从当前分支到默认分支之间所有拥有 open PR 的分支都找出来列成一张链。链里的每个节点都代表一个 PR每个节点都依赖前一个节点。这个答案是动态的只要有人改了 base链就会变。另一种答案是“它曾经属于某条链但现在已经不属于了”。比如链上第一个 PR 已经合入base 分支被删除后续 PR 的 base 虽然还指向旧分支但该分支已经不再是活动分支。这种情况更多是历史遗留问题你需要处理的是“过时的 base 引用”而不是“当前属于哪个栈”。还有一种答案是“它看起来在链上但实际上链已经断了”。例如 base 分支存在但它的 PR 被关闭了。如果脚本只查 open PR很可能会在这里卡住。这时候你要么把已关闭的 PR 也纳入查询要么直接找开发确认。我倾向于把“判断分支是否属于某个 Stacked PR”看作是一次 PR 元数据查询而不是一次 Git 历史考古。掌握了这个视角你就不会在git log和图谱里越陷越深。真正长期有价值的能力是让团队的 Stacked PR 工作流变得可以被机器查询。无论是通过ghCLI 写脚本还是在 PR 模板里强制要求填写依赖信息都是为了给“判断归属”这件事提供明确依据。等到有一天你不再需要打开 GitHub 页面逐层翻找而是敲一条命令就能得到完整依赖链这时候才算真的掌握了 Stacked PR 这种开发方式。
如何判断一个分支是否属于某个GitHub Stacked PR？
在团队协作里最容易被当成小事忽略、最后却把人卡住的往往不是代码冲突而是一个看起来很基础的问题当前这个分支到底是不是某个 GitHub Stacked PR 的一部分这个疑问我经常遇到。比如你接手一个已经迭代了两周的开发分支Git 历史里全是feat: xxx、chore: yyyPR 列表里开着七八个看起来都有关联的 pull request你并不知道自己站在哪一环。又或者团队其他人问你“你那个分支是不是挂在刚才那组 stacked PR 下面如果第一个 PR 被合了后面几个要不要一起 rebase”你打开 GitHub 翻了几页最后只能靠猜。很多人会以为这是 Git 使用不熟练的问题多学几个命令就能解决。但真不是。Stacked PR 本身是 GitHub 工作流的一种特殊用法Git 只能确认提交之间的父子关系而“分支属于哪个 Stacked PR”是一个 PR 元数据问题。要可靠地判断必须换一套思路。1. Stacked PR 为什么会让“一个分支属于谁”变成难题1.1 先讲清楚 Stacked PR 到底是什么所谓 Stacked PR通常不是 GitHub 官方提供的一个独立功能而是一套通过分支依赖关系组织 PR 批次的工作流。普通 PR 的结构很简单feature分支直接对比mainPR 合并后 feature 分支进入 main。一次只处理一个改动。Stacked PR 则不同。一个大功能被拆成多个小功能每个小功能各自对应一个分支和 PR但这些 PR 并不是各自独立指向 main而是形成一条链PR #1: feat-base - mainPR #2: feat-2 - feat-basePR #3: feat-3 - feat-2也就是说后一个 PR 的 base 分支是前一个 PR 的 head 分支。最后一个 PR 的 base 才是 main。这样每个 PR 的 diff 只包含自己那部分改动reviewer 可以先 review 第一层再顺序往下看。只要第一层合入 main把后续分支 rebase 到新的 main 上链上后续 PR 的 diff 依然干净不会混入已经审查过的代码。这种做法的价值很明显。一个大产品功能往往涉及接口设计、核心逻辑、UI 呈现、测试补充如果全部塞进一个 PRreviewer 很难消化。拆成 Stacked PR 后每次 review 的差异都聚焦在一个最小单位审批速度会快很多。但代价也就在“链”这个字上。只要有链就有上下游关系就有“这个分支是不是属于某条链”的归属问题。1.2 为什么 GitHub 的普通 PR 流程没有专门回答这个问题如果你每天都在用普通 PR基本不会问“这个分支是不是属于某个 Stacked PR”。因为普通 PR 里分支归属很清晰分支指向 main就是一个独立 PR分支不指向 main那就还没准备好。不存在“链”的概念。Stacked PR 打破了这种清晰边界。分支不再只是“面向 main 的一个开发单元”它可能是链中间的一个环节也可能是链的开头还可能已经脱离了原来那条链。GitHub 的 PR 页面虽然会显示 base 分支和 head 分支但没有一个汇总视图告诉你“这条分支从属于哪一条依赖链”。默认只能看到一层一个 PR 的 base 是什么。你点进 base 分支对应的 PR又能看到它的 base 是什么这样一层层往上翻才能还原出完整的链。这个“逐层翻”的动作就是问题核心。Git 不会记录“PR 依赖关系”它只记录 commit 的父子关系和历史。你从git log里可以看到两个分支共享哪些提交但看不到“这个分支被哪个 PR 引用为 base”。所以要回答“我的分支是不是某个 Stacked PR 的一部分”本质上不是一个 Git 操作而是一个 PR 元数据查询。你需要查的是这个分支上有没有 PR这个 PR 的 base 是什么base 上有没有另一个 PR一路往上能不能走到默认分支。1.3 这个问题会在哪些场景变成真正的阻塞如果只是偶尔用一次 Stacked PR判断分支归属可能只是“确认一下”。但实际工作流里下面几个场景经常会被它卡住。第一个场景是多层 PR 的 rebase。链上的第一个 PR 合入 main 后后续 PR 的 base 分支往往需要 rebase 到新的 main 上。如果你手里有七八个分支又不知道哪些分支属于同一条链就很可能会漏掉某个依赖分支导致后续 CI 报一堆错误。第二个场景是 Review 之前的准备。你作为 reviewer 收到一个 PR发现 base 不是一个已合入的主分支而是一个看起来还在开发中的分支。这时你需要判断“这个 PR 是不是 stacked 链的一部分”才能决定自己应该只看这个 PR 的 diff还是需要连同 base 分支的改动一起理解。第三个场景是分支清理。项目上线后开发者会删除已经合入的分支。Stacked PR 链上如果中间某个 PR 被合并而下游 PR 还没合入直接删除 base 分支会导致下游 PR 的 base 引用变得不清晰。如果你能准确判断哪些分支还挂在链上就不会误删依赖。这几个场景说明判断分支归属不是一个“锦上添花”的小技巧而是维护 Stacked PR 工作流的基本能力。2. 别被分支名、提交历史和 GitHub UI 骗了2.1 分支名和 commit message 只能提供线索不能作为判断依据最容易想到的方法是看名字。很多团队在拆 Stacked PR 时会用feat/user/1、feat/user/2、feat/user/3这种带序号的分支名或者a/stack-xxx这样带前缀的命名。看到这种名字你确实能大概猜出分支之间的顺序。但分支名是写给人看的不是程序逻辑。GitHub 在计算 PR 依赖时完全不看分支名叫什么。你完全可以把feat/user/3分支的 base 设置成 main也可以把feat/user/1分支的 base 设置成另一个分支。只要有人手动改过 base分支名就失去意义。commit message 也一样。有人会在提交信息里写stacked on top of ...但这种信息不是结构化数据。一旦经过 rebasecommit message 可能会被改写而且无法被脚本稳定解析。如果你要根据 commit 信息来做自动化判断迟早会遇到一个没按约定写提交的开发。所以我的建议是分支名和 commit message 只能作为辅助观察永远不要作为最终结论。2.2git log和git merge-base只能说明“提交重叠”不能说明“PR 依赖”还有一种容易踩坑的做法是想通过 Git 历史来判断。比如你会git log --oneline --graph看到某个分支的提交历史里包含了另一个分支的 recent commit于是认为它们属于同一个 Stacked PR。这个推论在大多数情况下是正确的但不保证。Git 是一个提交图某个分支的提交历史里包含另一个分支的提交只表示它们之间存在祖先关系。这种关系可能来自 Stacked PR也可能来自一次简单的 merge甚至可能是一个长期维护分支从另一个 release 分支同步代码。仅凭 Git 历史你无法判断这两个分支是否被同一个 PR 链管理。git merge-base也只是找到两个分支的共同祖先它不能告诉你 PR 的 base 怎么设置。两个分支可能共享同一个祖先但一个是独立 PR另一个挂在 Stacked PR 链上。你能看到的只是历史有交集看不到 GitHub 上的 PR 依赖元数据。因此用纯 Git 命令判断 Stacked PR 归属方向就错了。2.3 GitHub UI 的默认视图也不够直观在 GitHub 上打开任意一个 PR页面会显示“base: main - head: feature”。你要是顺着 base 判断也能找到上游 PR。但 GitHub 的默认 UI 只展示当前 PR 这一层的 base它不会主动告诉你“这个 base 分支是另一个 PR 的 head”。如果你在某个 PR 页面看到 base 分支是一个非 main 分支你需要手动点击这个 base 分支名找到它对应的 PR再查看它的 base再继续点击。这种操作在链只有两三层时还能忍受一旦链上有五六个 PR逐层点击非常容易看漏而且页面状态会来回跳。还有一个更隐蔽的问题PR 是动态的。base 分支可以被修改你上一次看到的关系可能在下一次刷新后就不一样了。GitHub UI 适合作为人工确认的辅助工具不适合作为系统判断的唯一来源。3. 一个可靠的手动判断法沿 base 分支一层层向上查3.1 核心思路用 PR 的baseRefName和headRefName还原依赖链既然问题出在 PR 元数据上那么最可靠的方法就是直接读 PR 的元数据。在 GitHub 的 PR 结构里有两个关键字段headRefName当前这个 PR 对应的分支也就是改动所在的分支。baseRefName当前这个 PR 要合入的目标分支。对于一个普通 PRbaseRefName 通常是main、master、develop这类基础分支。但对于 Stacked PR 链上的 PR它的 baseRefName 往往是另一个分支的名字而且这个分支很可能就是另一个 PR 的 headRefName。所以判断“当前分支是否属于某个 Stacked PR”可以变成这样一个递归查询查当前分支是否有对应 PR。如果有看这个 PR 的 baseRefName 是什么。如果 baseRefName 不是默认分支再去查名为 baseRefName 的分支是否有对应 PR。重复这个过程直到 baseRefName 是默认分支或者找不到对应 PR。这个过程就是还原 Stacked PR 依赖链的过程。如果当前分支在链上最终会走到默认分支如果不在链上第一步就会发现它根本没有任何 PR或者它的 base 直接就是默认分支。3.2 用 GitHub CLI 手动查依赖链如果你的机器上安装了 GitHub CLIgh并且已经登录那手动判断非常快。先确认当前分支git branch --show-current假设当前分支是feat/stack-2然后用 gh 查看这个分支的 PRgh pr view feat/stack-2 --json number,baseRefName,headRefName,state,url输出大概是{ number: 123, baseRefName: feat/stack-1, headRefName: feat/stack-2, state: OPEN, url: https://github.com/your/repo/pull/123 }看到baseRefName是feat/stack-1说明这很可能不是最终 PR。继续查feat/stack-1:gh pr view feat/stack-1 --json number,baseRefName,headRefName,state,url如果feat/stack-1的baseRefName是main那链条就清楚了feat/stack-2 - feat/stack-1 - main当前分支属于一个长度为 2 的 Stacked PR 链。如果feat/stack-1也有自己的 base那就继续向上查。这套方法的好处是它不依赖分支名也不依赖 commit message只看 GitHub 上真实的 PR 元数据。只要 baseRefName 设置正确结论就是可靠的。3.3 三种典型结果以及每一种的含义手动查完之后通常会遇到三种情况。我列成表方便对比。当前分支对应的 PRPR 的 baseRefName结论有且状态 OPENmain 或默认分支独立 PR不属于任何 Stacked PR 链有且状态 OPEN另一个非默认分支而该分支也有 OPEN PR当前分支在某个 Stacked PR 链上有但状态合并/关闭另一个非默认分支需要进一步确认可能是链已被部分合入也可能是历史遗留第一种情况最简单直接回复“它就是一个独立 PR”。第二种情况就是 Stacked PR 链的一部分。第三种情况要小心因为链上可能已经有一部分 PR 合入 main剩下的 PR 还挂在旧分支上。这时候需要把向上递归的范围扩大把已合入 PR 也纳入查询。除了这三种情况还有一个边界当前分支根本没有 PR。这时不能直接说“不属于任何 Stacked PR”。你手上有代码但还没推送或者 PR 还没创建。GitHub 上没有 PR 元数据就无法判断。这种情况下应该先确认开发者意图再决定下一步。4. 把判断流程固化成脚本和团队约定4.1 为什么值得脚本化手动查依赖链虽然可靠但每查一个分支都要敲一遍gh pr view如果链很长效率并不高。更重要的是手动查询很容易在多个终端窗口之间遗漏。你刚查完 PR #123 的 base 是feat/stack-1切到另一个窗口去查看feat/stack-1的 PR再切回来时可能已经忘了前面几层的结构。把流程固化成脚本至少可以让每次判断有可复现的输出。我自己一般会先写一个最小脚本确保逻辑正确再逐步扩充。这里给你一个可以直接实验的 bash 示例结构#!/usr/bin/env bash set -euo pipefail DEFAULT_BRANCH${1:-main} current_branch$(git branch --show-current) branch$current_branch echo Current branch: $branch echo DEFAULT_BRANCH: $DEFAULT_BRANCH echo --- for ((i 0; i 10; i)); do # 查询当前分支对应的 open PR pr_json$(gh pr list --head $branch --json number,baseRefName,headRefName,state --limit 1 2/dev/null || true) if [[ -z $pr_json || $pr_json [] ]]; then echo No open PR found for branch: $branch break fi number$(echo $pr_json | jq -r .[0].number) base$(echo $pr_json | jq -r .[0].baseRefName) head$(echo $pr_json | jq -r .[0].headRefName) state$(echo $pr_json | jq -r .[0].state) echo PR #$number: $head - $base (state: $state) if [[ $base $DEFAULT_BRANCH ]]; then echo Found default branch base. End of chain. break fi branch$base done这段脚本的逻辑很简单从当前分支开始不断查询以当前分支为 head 的 open PR如果 PR 的 base 不是默认分支就把 base 当作下一个要查询的分支继续循环。为了防止意外死循环我加了10层深度限制。使用前需要有ghCLI、jq和 GitHub 登录授权。如果你没装jq也可以用 python 替代。脚本只是示例不是开箱即用的生产工具因为实际项目里可能还有 fork 场景、多仓库场景、草稿 PR 场景这些都需要单独处理。4.2 进阶脚本返回完整 PR 链而不是只告诉你“是不是”上面这个脚本只负责把链路打印出来严格说并没有直接回答“是不是 Stacked PR 的一部分”。如果想要一个更明确的判断结果可以把链路收集到一个数组里最后输出结论。Python 写起来会更清晰。伪码思路如下获取当前分支名。循环最多 10 次调用gh pr list --head branch --json number,baseRefName。如果查不到记录“无 PR”退出。如果查到多个 PR这种场景很少但可能出现优先取 state 为 OPEN 的那一个或者提示用户指定。把当前 PR 信息 append 到链列表。如果 base 是默认分支标记为“到达链顶”退出。否则将branch替换为base继续循环。输出链列表以及“当前分支是否处于 Stacked PR 链上”的结论。这个脚本可以在团队内分享。因为每个团队的默认分支不一样最好让默认分支作为参数传入或者通过gh repo view --json defaultBranchRef获取。4.3 再往前一步用团队约定减少“事后判断”的次数脚本能解决“我已经有了一个分支怎么判断它属于谁”的问题但不能解决“为什么会形成这种混乱”的问题。真正高效的做法是在源头上减少模糊性。一个比较实用的约定是Stacked PR 链里的每个 PR都应该在 PR 描述里写明它依赖哪个 PR以及它的 base 分支应该指向哪个分支。可以是手写也可以是 PR 模板里增加一个栏位。在这个基础上分支命名也建议统一。不一定非要带序号但至少要让别人一眼能看出“这个分支看起来不是直接面向 main 的”。比如统一使用stack/功能名/层级或者feat/用户/功能/序号。注意这只是辅助不是判断依据。如果团队使用的 Stacked PR 频率很高也可以考虑引入专门管理栈的 CLI 工具。社区里已经有一些工具用来自动创建依赖分支、自动修改 base、rebase 后批量更新链上 PR。不过引入新工具会带来学习成本和流程调整建议先在少量分支上试用确认它能和你们的 GitHub 工作流兼容再推广到团队。我把这个过程总结成一个可复用框架叫“三层判断法”看元数据用gh pr list --head branch确认这个分支有没有 PR。看 base看 PR 的 baseRefName 是不是默认分支。向上递归base 不是默认分支时继续查 base 分支的 PR。这个框架适用于所有基于 GitHub 的 Stacked PR 工作流。5. 真正落地时需要注意的边界与排查链路5.1 脚本和手动查询都可能被哪些因素干扰有时候你得到的结论和预期不符不一定是 Stacked PR 定义变了而是查询过程踩了一些边界。第一PR 状态。上面脚本默认查询 open 状态的 PR。如果当前分支的 PR 处于 draft 状态它仍然是 open能不能算 Stacked PR 的一部分严格来说只要它的 base 是另一个非默认分支它就是链上的一环和 draft 无关。但如果 PR 被关闭脚本就会返回“无 open PR”这时不能直接下结论因为历史链可能已经被拆掉。第二base 分支已经合入默认分支。假设 PR #1 已经合入 mainPR #2 的 base 还是feat/stack-1但feat/stack-1已经合入 main 后被删除了。这时查feat/stack-1可能查不到 open PR但 PR #2 其实仍然是一个悬空的 Stacked PR或者说是一个“曾经属于 Stacked PR、现在 base 过时的 PR”。判断时要看 base 分支是否等于默认分支而不是看 base 分支还存不存在。第三fork 仓库的 head 分支。如果开发者在 fork 仓库里工作gh pr list --head branch可能需要指定--head owner:branch或--repo owner/upstream否则查不到。第四权限问题。如果你没有目标仓库的读取权限gh CLI 和 GitHub API 都可能返回空结果。拿到“没有 PR”的结果时先检查一下登录状态和仓库权限别急着下判断。5.2 一个值得记住的排查链路当你发现判断结果不稳定时建议按下面这个顺序排查确认仓库和分支信息git remote -v、git branch --show-current、git fetch是否已经同步最新远端状态。确认 gh CLI 状态gh auth status是否已经登录、gh repo set-default是否指向正确仓库。确认 PR 查询条件gh pr list --head branch是否真的返回了你想要的那条 PR是否因为 PR 状态不是 open 而被过滤。确认 base 分支gh pr view number --json baseRefName是否能正确返回而不是因为 fork 或 remote 问题读到空值。如果手动步骤都对但结果仍然奇怪就用最原始的方式确认打开 PR 的 GitHub 页面看 base 下拉框看“Merge”按钮上方显示的 base 分支再对比脚本输出。最后这一步看似笨但在自动化结果和人脑判断冲突时它可以帮助你判断是脚本逻辑问题还是自己对 Stacked PR 的理解有偏差。5.3 这个判断方法适用于哪些场景不适用于哪些场景从工具角度看这套方法只适用于 GitHub 仓库。如果你用的是 GitLab、Gitea 或者其他 Git 托管平台“merge request” 和 “PR” 的元数据结构不一样不能直接套用。但只要了解对应平台的 base 分支和 source 分支概念思路是相通的。从团队规模看Stacked PR 更适合有一定协作经验、代码评审规范比较成熟的团队。如果你刚使用 GitHub 不久或者团队只有两三人我建议先老老实实走普通 PR 流程至少把 main 分支的稳定性维护好。Stacked PR 只是把一个大的 diff 分散到多个 PR 里并不会自动让代码变好。如果 review 习惯不好只是多了一堆互相依赖的 PR 需要照顾而已。还要注意Stacked PR 不是银弹。它适用于跨多个代码模块的大功能但不适用于所有改动。比如一个简单的 bug 修复拆成三层就完全没有必要。判断分支是否属于 Stacked PR 的能力是为了更好地掌握这种工作流而不是为了鼓励把所有改动都做成栈。注意不要因为脚本能自动判断就放弃人工 review 对 base 分支的确认。脚本只是把“当前分支是不是在栈上”这个问题回答得更快但“这个栈设置得合不合理”仍然需要人来判断。6. 回到最初的问题先确定你的工作流需要哪种答案如果回到文章开头那个问题“这个分支是不是某个 GitHub Stacked PR 的一部分”你会发现答案并不是非黑即白。有一种答案是“它现在属于这条链”这时你需要把从当前分支到默认分支之间所有拥有 open PR 的分支都找出来列成一张链。链里的每个节点都代表一个 PR每个节点都依赖前一个节点。这个答案是动态的只要有人改了 base链就会变。另一种答案是“它曾经属于某条链但现在已经不属于了”。比如链上第一个 PR 已经合入base 分支被删除后续 PR 的 base 虽然还指向旧分支但该分支已经不再是活动分支。这种情况更多是历史遗留问题你需要处理的是“过时的 base 引用”而不是“当前属于哪个栈”。还有一种答案是“它看起来在链上但实际上链已经断了”。例如 base 分支存在但它的 PR 被关闭了。如果脚本只查 open PR很可能会在这里卡住。这时候你要么把已关闭的 PR 也纳入查询要么直接找开发确认。我倾向于把“判断分支是否属于某个 Stacked PR”看作是一次 PR 元数据查询而不是一次 Git 历史考古。掌握了这个视角你就不会在git log和图谱里越陷越深。真正长期有价值的能力是让团队的 Stacked PR 工作流变得可以被机器查询。无论是通过ghCLI 写脚本还是在 PR 模板里强制要求填写依赖信息都是为了给“判断归属”这件事提供明确依据。等到有一天你不再需要打开 GitHub 页面逐层翻找而是敲一条命令就能得到完整依赖链这时候才算真的掌握了 Stacked PR 这种开发方式。
