update-branch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Update Branch

更新分支

Quick Start

快速开始

Invoke from a local work branch:

text

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

No argument means resolve the base from

origin/HEAD

. An optional base argument selects another branch or remote-tracking ref. Dirty work normally stops the update; a clearly cohesive, branch-local, non-silent auto-commit with explicit operator confirmation is the only exception. Dependency refresh is conditional on dependency-related files changing during the merge; do not reinstall dependencies unconditionally on every branch update.

This skill is local-first. Use pure

git

; do not use

gh pr update-branch

, GitHub's remote update button, or any GitHub update API. Never push automatically.

在本地工作分支中调用：

text

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

无参数表示从

origin/HEAD

解析基础分支。可选的基础参数可选择其他分支或远程跟踪引用。通常，工作区有未提交更改会阻止更新；唯一的例外是：当所有未提交更改具有明确的内聚性、属于当前分支本地内容，且在获得操作者明确确认后，执行非静默的自动提交（提交信息符合规范）。仅当合并过程中依赖相关文件发生变化时才刷新依赖；不要在每次分支更新时无条件重新安装依赖。

此技能优先本地操作。仅使用纯

git

命令；不要使用

gh pr update-branch

、GitHub的远程更新按钮或任何GitHub更新API。绝不自动推送。

Input Contract

输入约定

Accept no argument or one optional base ref.
Refuse detached HEAD.
Refuse a missing
```
origin
```
remote.
When no base is supplied, refuse missing
```
origin/HEAD
```
; do not hardcode
```
main
```
,
```
master
```
, or another default branch. Tell the operator to run
```
git remote set-head origin -a
```
when
```
origin/HEAD
```
is missing.
Refuse to update the repository default branch unless the user explicitly supplies a base and confirms they intend to mutate that branch.

接受无参数或一个可选的基础引用。
拒绝分离HEAD状态。
拒绝缺少
```
origin
```
远程仓库的情况。
当未提供基础分支时，若缺少
```
origin/HEAD
```
则拒绝执行；不要硬编码
```
main
```
、
```
master
```
或其他默认分支。当
```
origin/HEAD
```
缺失时，告知操作者运行
```
git remote set-head origin -a
```
。
拒绝更新仓库默认分支，除非用户明确提供基础分支并确认他们有意修改该分支。

Workflow

工作流程

Read repository guidance for commit messages, verification, and protected branches.
Record the current branch with
```
git branch --show-current
```
. Before fetch or merge, compare it to the repository default branch. If they match, stop unless the user supplied a base and explicitly confirmed they intend to update the default branch.
Resolve the base:
- With an optional base argument, normalize any bare branch name, such as
```
main
```
  ,
```
master
```
  ,
```
develop
```
  ,
```
trunk
```
  , or
```
release/1.x
```
  , to its
```
origin/<name>
```
  remote-tracking ref. Keep remote-tracking refs such as
```
origin/release/1.x
```
  as supplied.
- Without an argument, read
```
refs/remotes/origin/HEAD
```
  and normalize it to the remote-tracking branch it points at, such as
```
origin/main
```
  .
Fetch the remote head name for the selected base from
```
origin
```
, stripping the leading
```
origin/
```
first. For example, fetch
```
main
```
for
```
origin/main
```
and
```
release/1.x
```
for
```
origin/release/1.x
```
.
Inspect local dirty state before merging:
- Run
```
git status --short
```
  .
- Review staged, unstaged, and untracked diffs.
- Auto-commit only when the entire dirty set is cohesive, branch-local, free of secrets, and can be summarized under the local commit convention. Before committing, state the exact files and commit message that will be used, then wait for explicit operator confirmation so the auto-commit is not silent. Without confirmation, including in non-interactive runs, stop and report the dirty state.
- Stop for unrelated or ambiguous changes, such as a mixed app, config, and generated-file dirty set; generated output with unclear source; possible secrets; or any commit-message requirement, such as a required issue tag, that cannot be satisfied from local guidance.
Merge with an explicit merge commit:
- Run
```
git merge --no-ff <base-ref>
```
  .
- If Git reports
```
Already up to date
```
  , report that no merge commit was needed.
Resolve conflicts only when the correct resolution is obvious, branch-local, in scope, and mechanically verifiable. Stop for product judgment, unrelated scope, permissions, secrets, generated-file uncertainty, or unverifiable semantics.
After a successful merge or conflict resolution, inspect whether dependency inputs changed during the merge. Treat package manifests, lockfiles, workspace manifests, or toolchain version files as dependency inputs.
- When dependency inputs changed, run the repository's documented install/bootstrap command before verification. Prefer commands in
```
AGENTS.md
```
  , README files, package scripts, or other repository guidance.
- If dependency inputs changed and no install/bootstrap command is documented, stop and report that dependencies may need refresh before verification can run.
- Do not silently commit lockfile or generated dependency changes. Include them only when they are a direct result of the documented install command, are in scope for the branch update, and follow the same explicit confirmation and commit-message rules as other auto-committed dirty work.
Run documented verification after auto-committing dirty work, completing dependency refresh, or completing conflict resolution. Prefer commands in
```
AGENTS.md
```
, README files, package scripts, or other repository guidance. If no local verification applies, say so explicitly.
Report the result without pushing.

读取仓库关于提交信息、验证和受保护分支的指南。
使用
```
git branch --show-current
```
记录当前分支。在拉取或合并前，将其与仓库默认分支对比。若两者匹配，则停止操作，除非用户提供了基础分支并明确确认他们有意更新默认分支。
解析基础分支：
- 若提供了可选的基础参数，将任何裸分支名（如
```
main
```
  、
```
master
```
  、
```
develop
```
  、
```
trunk
```
  或
```
release/1.x
```
  ）规范化为对应的
```
origin/<name>
```
  远程跟踪引用。对于已有的远程跟踪引用（如
```
origin/release/1.x
```
  ），保持原样。
- 若无参数，读取
```
refs/remotes/origin/HEAD
```
  并将其规范化为指向的远程跟踪分支，如
```
origin/main
```
  。
从
```
origin
```
拉取所选基础分支的远程头名称，先去掉开头的
```
origin/
```
。例如，对于
```
origin/main
```
拉取
```
main
```
，对于
```
origin/release/1.x
```
拉取
```
release/1.x
```
。
合并前检查本地工作区的脏状态：
- 运行
```
git status --short
```
  。
- 检查暂存、未暂存和未跟踪的差异。
- 仅当所有未提交更改具有明确的内聚性、属于当前分支本地内容、不包含敏感信息，且符合本地提交规范时，才执行自动提交。提交前，说明将使用的具体文件和提交信息，然后等待操作者明确确认，确保自动提交非静默。若无确认（包括非交互式运行），则停止操作并报告脏状态。
- 若存在无关或模糊的更改（如混合了应用、配置和生成文件的脏集合；来源不明的生成输出；可能包含敏感信息；或无法从本地指南满足的提交信息要求，如必填的问题标签），则停止操作。
使用显式合并提交进行合并：
- 运行
```
git merge --no-ff <base-ref>
```
  。
- 若Git提示
```
Already up to date
```
  ，则报告无需创建合并提交。
仅当冲突的正确解决方案明显、属于当前分支本地内容、在范围内且可机械验证时，才解决冲突。若涉及产品决策、无关范围、权限、敏感信息、生成文件不确定性或无法验证的语义，则停止操作。
成功合并或解决冲突后，检查合并过程中依赖输入是否发生变化。将包清单、锁定文件、工作区清单或工具链版本文件视为依赖输入。
- 若依赖输入发生变化，在验证前运行仓库文档中记录的安装/引导命令。优先选择
```
AGENTS.md
```
  、README文件、包脚本或其他仓库指南中的命令。
- 若依赖输入发生变化但无文档记录的安装/引导命令，则停止操作并报告在验证前可能需要刷新依赖。
- 不要静默提交锁定文件或生成的依赖更改。仅当这些更改是文档化安装命令的直接结果、属于分支更新范围，且遵循与其他自动提交的未完成工作相同的显式确认和提交信息规则时，才包含它们。
在自动提交未完成工作、完成依赖刷新或解决冲突后，运行文档化的验证命令。优先选择
```
AGENTS.md
```
、README文件、包脚本或其他仓库指南中的命令。若没有适用的本地验证命令，明确说明这一点。
报告操作结果，不执行推送。

Conflict Rules

冲突规则

Keep the merge in progress only while resolving clear branch-local conflicts.
Use
```
git merge --abort
```
before stopping when the branch should be restored to its pre-merge state.
Do not rebase, force-push, or rewrite history.
Do not sweep unrelated dirty files into the merge.

仅在解决明确的当前分支本地冲突时，保持合并进程。
当分支需要恢复到合并前状态时，在停止操作前运行
```
git merge --abort
```
。
不要执行变基、强制推送或重写历史。
不要将无关的未提交文件纳入合并。

Final Report

最终报告

Always include:

Current branch.
Base ref fetched and merged.
Whether a dirty-work auto-commit was created.
Whether a merge commit was created or the branch was already up to date.
Whether dependency refresh was skipped, run, or blocked because no documented install/bootstrap command was available.
Conflicts resolved or the human-owned blocker that stopped the workflow.
Documented verification commands and results, when run.
A clear note that the branch remains local-only.
The optional push command:
```
git push origin HEAD
```
.

必须包含以下内容：

当前分支。
拉取并合并的基础引用。
是否创建了未完成工作的自动提交。
是否创建了合并提交或分支已是最新状态。
依赖刷新是被跳过、已运行，还是因无文档记录的安装/引导命令而被阻止。
已解决的冲突，或阻止工作流继续的人工处理项。
已运行的文档化验证命令及其结果。
明确说明分支仍仅存在于本地。
可选的推送命令：
```
git push origin HEAD
```
。