用途:将 master 分支上的指定提交回移到某个发布分支。参数格式为 <commit-sha> <target-branch>,第一个参数是提交 SHA,第二个是目标分支。
主要能力:
- 流程保护:开始时记录当前分支,结束时无论成功或失败都切回该分支;工作区不干净时直接停止,不改变分支。
- 输入校验:先 git fetch origin,再用远端引用校验提交 SHA 与 origin/<目标分支> 是否存在,始终以远端引用为准,不在本地检出源提交或目标分支。
- 提交展示:通过 git show --stat 输出提交标题、作者、日期与改动文件统计。
- 链接生成:从 origin 远程地址推导 GitHub 仓库地址,生成提交链接;若提交标题含 (#NNN) 模式,生成对应 PR 链接,否则注明无法自动确定。
- 专用分支:以 backport/<短SHA>-to-<目标分支> 命名,直接从 origin/<目标分支> 创建;若分支已存在则停止,不覆盖。
- 仅回移源码:把改动文件分为版本文件(/package.json、/CHANGELOG.md,始终排除)与源码文件;若提交只改版本文件则停止。使用 git show <sha> -- <源码文件> | git apply --index 仅应用差异行,明确禁止用 git checkout <sha> -- <file> 整文件替换。
- 版本提醒:应用成功后先提交代码,并提示用户自行补充版本号与更新日志,运行 GITHUB_BASE_REF=origin/<目标分支> yarn nx release plan,等待用户确认。
- 推送与 PR:确认后推送分支,用 gh pr create 创建以目标分支为 base 的 PR,标题为“原标题 (backport to 目标分支)”,正文含摘要、测试计划等;若 gh 未认证,则输出手动创建 PR 的 URL 与标题正文。
- 冲突诊断:git apply 失败时不修改文件、不重试,而是用 merge-base 与三方对比(提交改动、目标分支现状、合并基点状态)判断冲突原因,如目标分支删除代码、代码移动或重构、并行冲突修改、文件重命名或删除、API 或导入变更,并给出具体手工处理建议。
使用方式:以技能形式调用,传入提交 SHA 与目标分支两个参数;全程按步骤执行,中途在版本更新处暂停等待用户确认。
适用场景:需要把 master 上的单个修复或改动安全回移到发布分支、并走 PR 审核流程的团队仓库,尤其适合使用 Nx release plan 管理版本与更新日志、使用 GitHub 与 gh CLI 的项目。
限制:依赖 GitHub 远程与 gh CLI;提交与目标分支须存在于 origin;只支持单个提交;不自动处理版本文件与冲突解决;PR 正文中的摘要需根据提交信息与改动文件撰写。