用途:把当前分支同步到基础分支。整个流程封装在 scripts/rebase-sync.sh 中,拆成多个子命令以便冲突时暂停、修复、继续;应驱动该脚本,不要手写 git fetch/rebase/push,因为脚本内含安全检查(在基础分支上重放会被拒绝、租约保护的推送、自动贮藏)。
两条路径:预检(preflight)会报告 STACK 行决定后续。STACK: stack 表示分支属于 GitHub 堆叠 PR 链且已安装 gh-stack,走堆叠路径(stack-sync);STACK: no-stack 或 no-extension 走普通路径(rebase → push)。堆叠路径先与用户确认,因为 gh stack sync 是一次性完成 fetch、rebase、push,没有中间检查点;随后依次为 stack-rebase、stack-continue、stack-abort、stack-sync。
普通路径步骤:先运行 preflight,确认分支、解析出的基础分支和是否脏工作区;基础分支自动从 origin/HEAD 检测,回退到 main/master/develop,可用参数指定。若因当前分支就是基础分支而退出,应停止并询问用户。然后运行 rebase,未提交内容会自动贮藏并在完成后恢复;退出码 10 表示冲突,脚本会列出冲突文件并保留 rebase 进行中状态。
解决冲突时必须注意 ours/theirs 相对合并是反的:ours 是基础分支版本,theirs 是被重放的提交。应尽量同时保留双方意图,不要整体选边;对每个文件 git add 后运行 continue,因逐提交重放可能再次退出 10,需循环直到 STATUS: rebased。若冲突确实含义不明,不要猜测,解释选项并询问用户;abort 可干净恢复。
推送前需确认:展示现在位于基础分支之上的提交、每个冲突的解决方式、以及下一步将强制推送 origin/<branch>;除非用户明确要求不要询问。push 使用 --force-with-lease(git 支持时加 --force-if-includes),绝不使用裸 --force。若报告 push-rejected,说明他人已推送该分支并列出强制推送会销毁的提交,此时应停止,不要升级为 --force,也不要重跑 rebase(它只抓取基础分支)。
限制与说明:堆叠路径中 sync 遇到冲突会保守回滚所有分支且不推送,需用 stack-rebase 逐个重放解决;sync-failed 通常表示本地与远程堆叠已分叉,需要交互式终端才会询问哪边获胜,脚本会中止而非猜测,应让用户在本地终端运行 gh stack sync。使用方式依赖该技能目录下的脚本;安装来源、平台与收费信息暂未提供。