update-branch

更新分支

从本地工作分支运行。

/update-branch
/update-branch release/1.x

当当前分支只有一个未关闭的拉取请求时，始终使用该拉取请求的目标分支，即使用户提供了其他目标分支也是如此。没有未关闭的拉取请求时，使用提供的目标分支；如果未提供，则回退到 origin/HEAD。

使用 git 执行获取和合并。仅使用 gh 读取拉取请求数据。随附的 scripts/update-context.sh 会选择目标分支并验证拉取请求上下文。没有拉取请求的分支会保留在本地。本次运行不会推送远程分支，除非操作员明确使用该辅助脚本的 push 命令请求更新远程分支。

要求

• 接受零个或一个目标参数。
• 如果处于分离 HEAD 状态或缺少 origin 远程，立即停止。
• 拉取请求查询必须使用 gh。查询失败属于错误，不能据此认定不存在拉取请求。
• 没有拉取请求或显式指定目标时，必须要求存在 origin/HEAD。如果缺少它，告知用户运行 git remote set-head origin -a。
• 绝不假设默认分支名为 main 或 master。
• 除非用户提供了目标分支，并明确确认应更改默认分支，否则不要更新仓库的默认分支。
• 对所有合并冲突使用 fix-merge-conflicts。编辑冲突前，运行 "$UPDATE_BRANCH_HELPER" require-conflict-skill。如果辅助脚本提示缺少该技能，则安装该技能或停止。

工作流

1. 阅读仓库中有关提交、检查和受保护分支的说明。

2. 记录 git branch --show-current 的结果，并将其与仓库默认分支进行比较。除非用户明确授权，否则处于默认分支时停止。

3. 将使用者仓库保留为工作目录。将此技能的安装目录解析为绝对路径，然后运行：

   UPDATE_BRANCH_HELPER="<absolute installed skill directory>/scripts/update-context.sh"
   "$UPDATE_BRANCH_HELPER" resolve [target]
   

   记录返回的模式、当前分支、规范化后的目标分支、拉取请求编号和 URL、拉取请求源分支，以及两个仓库的身份信息。辅助脚本要求获取远程与拉取请求的基础仓库匹配，并要求已配置的上游分支的推送 URL 与源仓库匹配。在工作流更改本地或远程状态之前，它会拒绝缺失、含糊或不匹配的身份信息。pull-request 模式使用拉取请求目标分支。local-only 模式使用显式指定的目标分支或 origin/HEAD。

4. 在目标分支中首次出现的 / 处分割，得到远程名称和分支名称。从该远程获取此分支。Fork 拉取请求可以选择诸如 upstream 之类的基础远程；仅本地模式的目标使用 origin。 记录 git rev-parse <target> 的结果，作为精确的目标提交。

5. 运行 git status --short，并检查已暂存、未暂存和未跟踪的文件。仅当所有已更改文件都属于同一项明确的更改、不包含可能的机密信息，且可使用仓库要求的提交格式时，才自动提交现有工作。提交前，告知用户确切的文件列表和提交消息。如果更改混杂或不明确、生成文件的来源未知、可能包含机密信息、或无法确定必须引用的问题编号，则停止。

6. 在不提交的情况下开始合并：

   git merge --no-commit --no-ff <target>
   

   如果 Git 提示 Already up to date，则无需创建合并提交。

7. 如果出现冲突，运行必需的技能检查；对于正确结果属于此更改且能够验证的冲突，使用 fix-merge-conflicts 解决。如果冲突需要产品决策、涉及无关工作、需要无法获得的访问权限、涉及机密处理或生成文件知识，或需要猜测行为，则中止合并并询问用户。在使用者仓库中运行技能检查：

   "$UPDATE_BRANCH_HELPER" require-conflict-skill
   

8. 检查合并是否更改了包清单、锁文件、工作区文件或工具链版本。如果有更改，请在验证前运行仓库说明中记录的安装或设置命令。如果没有记录任何命令，请停止。仅当该命令生成了依赖项变更，且这些变更属于此分支更新时，才将其纳入。

9. 运行仓库文档中记录的检查，以覆盖更改的代码、已解决的冲突和受影响的依赖项。如果没有适用的本地检查，请说明这一点。

   只有当仓库说明要求针对本次更改执行单独的全仓库检查时，才需要执行。如果必需或相关的检查失败，请中止合并并停止。

   如果相关检查通过，但额外的全仓库检查失败，只有在证明同一问题已存在于已获取的目标提交中后，才可以继续。可通过以下任一方式证明：

   • 失败源文件以及导致失败的规则、配置或输入与目标提交中的内容未发生变化
   • 在目标提交上运行该命令时出现相同的失败

   记录目标提交、命令、失败的检查和对比结果。如果分支更改了与失败有关的输入、合并导致了交互性失败，或仓库说明要求执行全仓库命令，则不要继续。在后续运行中，仅当目标提交、命令、失败的检查和对比结果均未变化时，才可复用该对比。

10. 如果验证后合并仍处于打开状态，请按照仓库的常规提交格式和钩子创建合并提交。

11. 完成时不要更改远程。在 pull-request 模式下，报告本地合并以及已捕获的拉取请求上下文。如果操作员明确要求更新远程，请运行：

    "$UPDATE_BRANCH_HELPER" push <pr-number> <target> <pr-head> <base-repository> <head-repository>
    

    原样传入 resolve 捕获的标识。该助手会验证拉取请求和两个远程标识，推送到配置的上游，并再次验证拉取请求。如果推送期间拉取请求发生变化或查询失败，请说明远程分支已变更，但拉取请求结果尚不确定。发生任何失败时，报告助手消息或失败的 git push 输出，不要声称拉取请求已更新。在 local-only 模式下，报告该分支尚未推送，并包含可选命令 git push origin HEAD。

合并安全

仅在解决由此分支更新涉及的明确冲突期间保持合并打开。停止前运行 git merge --abort，使分支恢复到合并前的状态。不要变基、强制推送、改写历史记录或纳入无关文件。

最终报告

报告当前分支、所选目标、目标的确切提交，以及目标的选择方式。说明现有工作是否已提交、是否创建了合并提交、是否刷新了依赖项、是否解决了冲突、检查是否通过，以及远程分支是否已推送。若额外的全仓库检查失败但未阻止更新，请包含目标提交、命令、失败的检查和对比结果。对于仅限本地的工作，请说明分支尚未推送，并包含 git push origin HEAD。