这两年团队从几十人长到三百多号人代码仓库也从单仓拆成了 monorepo我明显感觉到一个以前不太起眼的问题越来越扎眼一个功能拆得太细PR 就多PR 一多合并顺序就成了灾难。gstack 这个词如果只看字面写成小写就是“git stack”的缩略落到实操层面讲的是一种把多个独立提交像积木一样堆叠起来、各自单独评审、按依赖顺序逐个合入主干的协作方式。我最早是在 Graphite 的文档里看到这套玩法后来自己用原生 git 命令完整跑通了一遍才真正理解 gstack 背后的逻辑。这篇文章就把我对堆叠式 PR 工作流的拆解、实操过程和踩坑记录完整分享出来适合正在被大量相互关联的 PR 搞得焦头烂额的工程负责人也适合想把手动 git 操作效率提升一个档次的开发者。1. gstack 到底解决什么问题传统 PR 协作的死穴与出路1.1 传统单分支大 PR 的死穴先说一个大部分团队都遇到过的场景产品要上线一个“会员积分体系”拆开来有积分规则引擎、用户积分账户、签到任务、积分商城四块内容。按传统思路你开一个feature/member-points分支在这一个分支上连续提交三十多个 commit然后开一个 PRPR 标题写“会员积分体系”描述里贴一堆需求链接最后 at 三个 reviewer 来看。这个模式在项目小、提交少的时候没问题一旦分支活得超过一周、commit 超过二十个、参与的人超过两个痛点就全冒出来了。第一是评审范围爆炸reviewer 打开 PR 要面对几千行 diff上下文拆不清注意力很难集中在某一个逻辑点上经常出现“看了一下午还没看完三分之一”的情况。第二是合并阻塞模块 A 的代码如果还没被 review 通过模块 B 的代码就没法合入主分支哪怕模块 B 是完全独立的逻辑也必须跟着一起等。第三是长分支漂移分支在本地改得越久和主干的分叉就越大合并时冲突越多解决冲突的人心态越崩。这本质上不是 git 本身的问题而是工作流把“逻辑上可以拆开的多个任务”强行揉成了一个“大提交”。你想想生活中的快递打包如果一个大纸箱把所有易碎品堆在一起安检慢、运输风险高、任何一个环节出问题整箱都得被退回。更合理的做法是分层打包每层独立贴上标签逐层安检、逐层转运、按楼层顺序搬上楼。gstack 的思路就是这种“分层打包”。1.2 堆叠式工作的核心思想gstack 的模型很简单把一个大的功能需求拆成多个小的、逻辑上独立的 commit 或短分支让它们按依赖关系堆叠起来。每个 commit 或分支单独开一个 PR每个 PR 独立评审、独立测试但合并时必须按从底到顶的顺序来完成。举个例子把“会员积分体系”拆成 A积分规则引擎、B用户积分账户、C签到任务三层。主分支是 main你从 main 拉出feat/a做完 A 提交 commit再从feat/a拉出feat/b做完 B 提交再从feat/b拉出feat/c做完 C 提交。这时候 git 里就形成了一条链main → feat/a → feat/b → feat/c。这样做的收益是立竿见影的。A、B、C 三个 PR 可以同时挂着reviewer 不用等 A 合入 main 才开始看 B因为 PR 系统会自动计算“这个 PR 只显示这个分支相对于它下层分支的差异”所以 B 的 PR 里只显示 B 自己的改动不会把 A 的几十个文件强制塞给你看。合并顺序也能灵活安排A 先合B 在 A 合入后自动变成基于最新 main 的状态C 同理。每一层 PR 的 diff 规模都控制在几百行以内评审质量明显提升合并阻塞的时间被压缩到了最低。1.3 为什么以前没这么干现在却火了其实堆叠提交的概念很早就存在Linux 内核社区用的就是补丁系列patch series的方式stgit 这类工具十几年前就有了。但那时候主流代码托管平台的 UI 和底层计算都不支持“按依赖关系展示 PR 差异”你推上去一个包含下层改动的新分支平台会把下层改动也一并显示在 diff 里看起来就像重复提交体验很糟糕。近两年主流平台对堆叠 PR 的原生支持越来越完善GitHub 也推出了 stacked pull requests 的相关能力PR 的 diff 会自动根据目标分支和中间依赖分支的状态动态更新。Graphite 这类专门为堆叠工作流设计的工具也把“restack”“sync”“自动 rebase”这些繁琐操作包装成了几条命令。加上 monorepo 往大里做以后跨模块协作的规模越来越大大家才重新发现如果提交本身就是一张张有序的补丁那 gstack 就是最自然的协作方式。2. 手工搭建 gstack用原生 git 命令实现堆叠式 PR 全流程2.1 准备环境与创建堆叠分支理解 gstack 最好的方式是先用最朴素的 git 命令手动跑通一遍。不需要装任何额外工具只要本地安装的 git 版本支持--force-with-leaseGit 2.x 都支持就能完成整套流程。场景还是拿“会员积分体系”来说假设我已经从 main 拉出来一个干净的本地分支feat/a并且做好了模块 A 的代码提交记录是清晰的单条 commitgit checkout main git pull origin main git checkout -b feat/a # 在这里编写模块 A 的代码完成后提交 git add . git commit -m feat: 积分规则引擎基础实现接下来创建第二层。关键动作是必须从上一层的分支创建而不是从 main 创建。git checkout -b feat/b # 在这里编写模块 B 的代码注意要在 feat/a 的代码基础之上写 git add . git commit -m feat: 用户积分账户体系再创建第三层git checkout -b feat/c # 在这里编写模块 C 的代码依赖 feat/b git add . git commit -m feat: 签到任务接入积分账户这里有一个新手很容易犯的错误直接git checkout main git checkout -b feat/b这样 feat/b 基于的是 main并不包含 feat/a 的改动堆叠链就断了后面的“按依赖顺序合并”也没法成立。正确的逻辑是把“上一层分支”当作当前层的基础分支链式地往下生长。2.2 推送与开 PR 的正确姿势三个分支都创建好以后分别推送并开 PRgit push -u origin feat/a git push -u origin feat/b git push -u origin feat/c然后在 GitHub 上分别从feat/a、feat/b、feat/c向main开 PR。这里有个需要理解的底层机制B 的 PR diff 会包含 A 的改动因为feat/b的 commit 历史里本身就包含了feat/a的全部提交。当 A 合入 main 之后GitHub 会动态重新计算 B 的 diff自动把 A 已合入的改动排除掉B 的 PR 就只剩自己的内容了。所以在堆叠模式下你完全不用担心“B 的 PR 里怎么这么多 A 的代码”这正是正确的中间态。开 PR 时建议在 PR 描述里写明依赖关系比如 B 的 PR 标注depends on #123#123 是 A 的 PR 编号。这样 reviewer 和机器人工具都能识别堆叠顺序避免有人误以为 B 可以直接合入 main。这个依赖标注不仅是给人看的后面接自动化脚本时也是重要信号。2.3 更新和同步堆叠层从下往上 rebase堆叠模式最频繁的操作是“主干有更新了”或者“下层分支被合并了”之后同步整条链。原则只有一个从最底层开始逐层向上 rebase。假设过了一天main 上来了几个别人的 commit。我要做的是git fetch origin git checkout feat/a git rebase origin/main git push --force-with-lease origin feat/a git checkout feat/b git rebase feat/a git push --force-with-lease origin feat/b git checkout feat/c git rebase feat/b git push --force-with-lease origin feat/cfeat/a先 rebase 到最新的origin/mainfeat/b再 rebase 到更新后的feat/afeat/c再 rebase 到更新后的feat/b。这个顺序不能乱因为每一层都依赖下层的 commit 对象如果跳过某一层直接 rebase 上层链条会错位git 会按照“两个分支之间所有 commit 的差异”来计算冲突那冲突范围就会成倍放大。强制推送这里我必须强调一件事请使用--force-with-lease不要用裸的--force。--force-with-lease在推送前会检查远程分支是否和你上次看到的状态一致如果别人在你 fetch 之后又推送了新的 commit它会拒绝覆盖从源头上防止误伤队友。2.4 合并顺序与善后清理合并时就按从底到顶的顺序走。A 合入 main 后B 和 C 不需要立刻干活因为 PR 系统会自动把它们的 baseline 变成新的 main。但如果你的团队后续还有别的并行开发建议在 A 合入后主动执行一次 2.3 的同步流程把 B 和 C 重新 rebase 到最新的 main 上提前消灭潜在冲突。整条链合并完后清理远程分支git push origin --delete feat/a feat/b feat/c git branch -D feat/a feat/b feat/c到这里一个完整的 gstack 手工闭环就跑通了。你可能会觉得操作步骤比传统方式多确实前期建立堆叠分支、中期同步链、后期合并善后每一步都有固定动作。但请注意传统方式把所有这些成本集中放在了一个“大 PR 合并日”而 gstack 把成本分散到了每一次小步操作里总耗时其实更少重点是心理压力小太多了。3. 不想手搓Graphite 与 gh 脚本的工程化选型解析3.1 何时该上工具何时该手搓手工 git 命令虽然万无一失但堆叠层数一多比如超过三层每一次同步都要逐分支 checkout、rebase、push操作繁琐且容易漏。我个人的判断标准是团队每周堆叠 PR 数量超过十个或者单条堆叠链经常超过三层就应该引入工具自动化。工具的核心价值不是取代你对 git 的理解而是把“restack”这种高频动作压缩成一条命令并且用依赖感知的方式帮你避免顺序错误。下面这个表格对比了我在实际工程里用过的三类方案方案底层实现核心能力适用场景学习成本原生 git 命令git 本身无依赖、全平台可用、逻辑透明理解原理、临时协作、堆叠层数少的项目低Graphite (gt)封装 git用提交记录重建堆栈自动 restack、sync、依赖感知 checkout、可视化深度堆叠、多人统一协作、工程效率要求高中gh CLI 脚本官方 GitHub CLI bash/JavaScript批量创建 PR、标注依赖关系、自动处理 base不想引入新工具、纯 GitHub 环境低到中3.2 Graphite 实操从 gt init 到 gt restackGraphite 是我目前团队在用的方案它的核心抽象是“stack”让分支之间天然存在父子关系。我先把上一个案例用 Graphite 命令重放一遍。# 安装后先登录 gt auth login # 从 main 拉一个新的分支同时注册到 stack gt branch create feat/a # 写完代码、普通 git commit git commit -m feat: 积分规则引擎基础实现 # 创建第二层 gt branch create feat/b git commit -m feat: 用户积分账户体系 # 创建第三层 gt branch create feat/c git commit -m feat: 签到任务接入积分账户全部提交完后一条命令批量提交所有层的 PRgt submit它会自动识别main → feat/a → feat/b → feat/c这条链为每一层创建独立 PR并标注依赖关系。后续主干有了新变化我只需要gt syncGraphite 会自动从底层开始 rebase 整条链处理每个分支的更新并把更新推到远程。如果某一层出现冲突它会停在那里告诉你冲突文件解决后继续往上处理。这一点比手工逐分支执行要省太多时间。Graphite 还支持gt log查看堆叠状态、gt restack在不改变代码内容的情况下重新理顺分支关系都是高频实用的命令。3.3 纯脚本方案用 gh 实现堆叠 PR 的轻量化闭环如果团队不想引入 Graphite也不想上付费版的企业工具只想在 GitHub 上实现堆叠 PR 的批量创建那么用 gh CLI 写一个小脚本就够了。核心思路是遍历当前分支到目标基础分支之间的所有“中间分支”为每个分支计算它的 parent 分支然后调用 gh pr create。我实际用过的一段临时脚本逻辑如下伪代码方向for branch in feat/a feat/b feat/c; do if [ $branch feat/a ]; then basemain else # 依赖前一个分支这里通过命名约定推断 base上一层的分支名 fi gh pr create --base main --head $branch \ --title PR for $branch \ --body depends on #PR编号 done脚本本身不难难在两条一是依赖关系要维护准确二是在 A 合入后 B 的 base 要能自动感知。这个方案适合团队里只有一两个人需要做堆叠、且分支命名规范非常稳定的小场景。我建议如果真要长期走堆叠流程别把时间浪费在维护自己的脚本上Graphite 这类工具把复杂的 restack 逻辑已经打磨得很成熟了直接用省心得多。4. 堆叠实战的常见问题与排查技巧实录4.1 冲突集中爆发时按什么顺序解堆叠模式下的冲突有一个特征如果下层分支和主干发生冲突上层分支大概率也会跟着冲突因为上层分支包含下层分支的全部内容。很多第一次用堆叠的同事遇到冲突会很慌直接在最高层分支上拼命解冲突结果解完下一层又冲突白忙一场。正确的顺序永远是从最底层开始解。先让feat/arebaseorigin/main顺利通过再让feat/brebasefeat/a最后轮到feat/c。每一层的冲突解决完立即 commit 并 push下一层的 rebase 会基于更新后的下层进行。这个顺序能保证每个冲突文件只处理一次不会出现“解完了上层冲突下层又冒出同名文件冲突”的反复折腾。还有一个细节当feat/a的 rebase 过程产生冲突时git 会处于 detached HEAD 和 REBASE 中间态这时候不要直接git checkout其他分支去干别的。先把当前这层的冲突处理完确认 rebase 完成再离开。不然你会发现自己切到别的分支后这个中间态仍然挂着git 会拒绝你切走或者留下一个奇怪的临时分支。4.2 GitHub 上 PR 显示下层分支的改动正常吗这个问题几乎每周都会在 team chat 里出现一次新人看到feat/b的 PR 里有几十个文件都是feat/a的第一反应是“是不是我 base 选错了”。记住结论在堆叠模式下完全正常。原理是 GitHub 计算 PR diff 的方式是“比较 head 分支和 base 分支之间的差异”而feat/b的 commit 历史里包含feat/a的所有 commit所以 base 为 main 时diff 自然包含了 A 的全部改动。等 A 合入 main 后GitHub 会基于新的 main 重新计算 diffB 的改动会自动“缩水”到只显示自己引入的部分。这里有一个必须注意的禁忌不要把 B 的 PR base 手动改成feat/a因为这样下去GitHub 会把它当作“B 要合入 feat/a”而不是“B 要合入 main”整个堆叠顺序就乱了。如果你实在觉得 diff 看着难受可以在 PR 描述里明确标注“当前 PR 包含下层 PR #xxx 的内容该部分已在下层审阅”reviewer 看到这个说明就能自然理解。4.3 rebase 之后 CI 全量重跑成本爆炸怎么办堆叠模式会放大 CI 成本的焦虑因为每 rebase 一层那一层以及它上层所有 PR 的 commit 都会更新触发 CI 重跑。如果团队 CI 每次全量运行要二十分钟五层堆叠一起来就能拉满两个小时的排队。我的建议是做好三层分流。第一核心主干 PR 必须跑完整测试这是质量底线。第二中间层 PR 跑增量测试或模块级测试通过git diff获取改动文件列表只测试相关模块能把时间压缩到几分钟。第三把 CI 触发策略改成“只对栈顶 PR 跑完整测试”因为栈顶 PR 包含所有层的代码它能过说明整体没问题下层 PR 如果单独通过栈顶失败时再回查才是效率最高的做法。这套策略我在两个团队落地过CI 平均排队时间下降了六成质量事故没有增加。4.4 fixup 提交堆错位置或者顺序乱了怎么修堆叠模式下你可能会发现自己在feat/b分支上写了本应该属于feat/a的修复代码。传统 git 的交互式 rebase 能解决但堆叠链里的顺序调整要格外小心。一个比较稳的做法是用git commit --fixup配合git rebase --autosquashgit checkout feat/b git commit --fixupfeat/a 的那个 commit hash git rebase --autosquash feat/a--autosquash会自动把 fixup 提交放到它对应 commit 的下面并 squash 掉省去手动编辑 rebase 交互界面的步骤。但要注意这个操作会改变feat/a这个分支的提交历史所以执行完后从feat/b往上的所有分支都需要重新 rebase也就是重新跑一遍从下往上的 restack 流程。这也是为什么我建议先把 fixup 写在它真正所属的分支上尽量避免跨层修复因为跨层修复的操作成本真的不低。4.5 快速看清堆叠关系git log 的正确打开方式堆叠层数多了以后靠git branch或git log的默认视图很难快速判断当前状态。我常用的命令是git log --graph --oneline --decorate -20这个视图能把 commit 之间的分叉和堆叠关系用 ASCII 图形展现出来。配合git branch -vv可以看到每个分支追踪的远程分支和领先关系快速判断有没有提交忘记 push。Graphite 用户直接gt log就能看到带有依赖关系的栈状态视觉效果比原生命令友好很多。5. 团队落地 gstack 的经验与几个让我印象深刻的坑5.1 从中间层乱开分支依赖链直接断掉我见过最经典的翻车现场某同事在feat/b上工作到一半想单独实验一个小功能直接执行git checkout -b experiment。他没意识到这个动作会让experiment继承feat/b的全部未合入改动而experiment又不在原有的依赖链上。后面他发现实验代码里有 bug顺手在experiment上做了几个 fix最后想把这些 fix 合入feat/b时发现 git 历史已经乱成一团两边都包含对方的一部分改动无法干净地合并。正确的做法是需要从堆叠链上临时开“旁路分支”时明确这是短命实验分支不要让它反向影响主链。实验完成后用git cherry-pick把需要的关键 commit 摘回原分支而不是直接 merge 整个旁路分支。堆叠链的纪律是“链条只能从底部生长不能从中间随便分叉”。5.2 下沉合并后我忘了同步上层分支第三层直接冲突有一回feat/a合入 main 后我以为 PR 系统会自动帮feat/b和feat/c更新 base就没管它们。结果过了半天同事在feat/c上又加了一个小功能推送时提示冲突他打开一看冲突的是 main 上别人刚合入的一个公共组件文件而这个文件在feat/a合入时也动过。我这才意识到平台的 base 更新只影响 PR 显示并不会替你把本地分支 rebase 到新的 main 上。从那以后我给自己定了一个死规矩任何一个下层分支合入 main当天必须完成一次全链 restack。哪怕上层分支暂时没有新改动也要把 rebase 做了、push 了让远程分支始终和最新 main 对齐。拖延一天冲突概率成倍上升到第三天就完全不想动了。5.3 每层提交要能独立讲清楚一句话堆叠模式能不能成功的另一个重要因素是每一层 PR 是否真的“逻辑独立”。我评审时有个很朴素的标准如果我不能用一句话概括这个 PR 改了什么那这一层拆得就不合格。比如“修复了购物车金额计算的浮点精度问题”就是一句话能说清的而“重构了结算模块顺便把样式也调了”这种就不行应该拆成两层。每层 PR 保持足够小的规模不只是为了 review 体验更直接的影响是减少 rebase 时的冲突面。一个 300 行的独立 PR 和一个 3000 行的混合 PR在 rebase 时的冲突可能性完全不是一个量级。小步提交、短命分支、每层只做一个可描述的功能这三句话我每次给新人讲 gstack 时都会重复一遍。5.4 在工程团队里推广 gstack 的节奏建议最后说说推广。如果你在团队里想推动这种工作流我的建议是不要一步到位强推工具先带两三个核心同事用手工方式跑通一个小功能让大家直观感受“三层 PR 同时评审”是什么样的体验。体验建立起来后再引入 Graphite 或 gh 脚本自动化把操作成本降下来。期间固定一个每天五分钟的“restack 时间”谁的下层分支合入了同步喊一声大家一起把链刷一遍。这套方法我用了半年团队从最初只有我一个人堆叠发展到超过一半的并行开发任务都默认采用堆叠 PR合并阻塞基本消失code review 的痛苦指数也降了好几个档次。我个人现在处理三到五层的堆叠已经很少手工 rebase 了Graphite 把大部分机械操作都接管了过去但最核心的底层逻辑永远是那句话把提交当作一张张有序的补丁而不是一坨不可分割的工作。理解了这个心智模型无论你用原生命令还是专用工具思路都不会跑偏。真要说还有什么想嘱咐的就是别怕冲突堆叠模式下的冲突本质上是提前暴露的小问题按从底到顶的顺序解决每一次解决都会让你对依赖关系的理解更深一层。
