git-rebase-sync

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

git-rebase-sync

Use this skill when you need to sync a feature branch onto the latest

origin/{base_branch}

via git rebase, including conflict resolution with explicit clarification questions when intent is ambiguous.

当你需要通过git rebase将特性分支同步到最新的

origin/{base_branch}

时使用此技能，包括意图不明确时通过明确的澄清问题来完成冲突解决的场景。

Goals

目标

Rebase the current branch onto a specified base branch (often the repo default branch like
```
dev
```
or
```
main
```
).
Resolve conflicts deliberately, without guesswork.
Keep safety rails: backup ref, confirmations before history-rewriting commands, and safe pushing.

将当前分支变基到指定的基础分支（通常是仓库的默认分支，如
```
dev
```
或
```
main
```
）。
谨慎解决冲突，不做猜测。
保留安全防护：备份引用、执行修改历史的命令前确认、安全推送。

Hard Rules

硬性规则

Do not create or switch to a different feature branch. Operate on the current branch name unless I explicitly ask otherwise.
Before any history-rewriting command (
```
git rebase ...
```
,
```
git push --force*
```
), print the exact command(s) you will run and wait for my confirmation.
Create a local backup ref (prefer an annotated tag) before starting the rebase. Do not push backup refs unless I explicitly ask.
Prefer
```
git push --force-with-lease
```
, never plain
```
--force
```
.
If the correct conflict resolution is unclear, stop and ask a targeted question. Do not invent product behavior.

请勿创建或切换到其他特性分支。除非我明确要求，否则仅在当前分支上操作。
在执行任何修改历史的命令（
```
git rebase ...
```
、
```
git push --force*
```
）前，打印你将要运行的准确命令并等待我的确认。
开始变基前创建本地备份引用（优先使用附注标签）。除非我明确要求，否则不要推送备份引用。
优先使用
```
git push --force-with-lease
```
，绝对不要使用普通的
```
--force
```
。
如果不清楚正确的冲突解决方案，请停止并提出针对性问题，不要臆造产品行为。

Workflow

工作流程

1) Identify base + branch

1) 确定基础分支和当前分支

Determine the current branch:
- ```
git branch --show-current
```
Determine the base branch you will rebase onto:
- If not provided, use GitHub default branch:
  - ```
  gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
```
Fetch latest:
- ```
git fetch origin
```

确定当前分支：
- ```
git branch --show-current
```
确定你要变基到的基础分支：
- 如果未提供，使用GitHub默认分支：
  - ```
  gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
```
拉取最新代码：
- ```
git fetch origin
```

2) Preflight safety checks

2) 预飞行安全检查

Ensure the working tree is clean and there is no operation in progress:
- ```
git status
```
If
```
git status
```
indicates an in-progress merge/rebase/cherry-pick, stop and ask what to do (abort vs continue).

确保工作树干净，没有正在进行的操作：
- ```
git status
```
如果
```
git status
```
显示有正在进行的合并/变基/拣选操作，停止并询问如何处理（中止还是继续）。

3) Create a local backup ref (do not push)

3) 创建本地备份引用（不要推送）

Create an annotated tag at current

HEAD

git tag -a {branch_name}-rebase-backup-$(date +%Y%m%d-%H%M%S) -m "pre-rebase backup" HEAD

Record the tag name as
```
{backup_ref}
```
for recovery.

在当前

HEAD

处创建附注标签：

git tag -a {branch_name}-rebase-backup-$(date +%Y%m%d-%H%M%S) -m "pre-rebase backup" HEAD

记录标签名为
```
{backup_ref}
```
以便恢复。

4) Choose rebase mode (normal vs preserve merges)

4) 选择变基模式（普通模式 vs 保留合并模式）

Check whether the branch contains merge commits:

git rev-list --count --merges origin/{base_branch}..HEAD

If merge commits exist, ask whether to preserve them (
```
--rebase-merges
```
) or flatten them (plain rebase).

检查分支是否包含合并提交：

git rev-list --count --merges origin/{base_branch}..HEAD

如果存在合并提交，询问是要保留合并（
```
--rebase-merges
```
）还是扁平化提交（普通变基）。

5) Run the rebase (requires confirmation)

5) 执行变基（需要确认）

Print the exact command you intend to run, then wait for confirmation:
- Typical:
  - ```
  git rebase origin/{base_branch}
```
- With merge preservation:
  - ```
  git rebase --rebase-merges origin/{base_branch}
```

打印你打算运行的准确命令，然后等待确认：
- 常规场景：
  - ```
  git rebase origin/{base_branch}
```
- 保留合并场景：
  - ```
  git rebase --rebase-merges origin/{base_branch}
```

6) Conflict handling loop

6) 冲突处理循环

When conflicts happen:

Collect context:
- ```
git status
```
- Identify conflicted files (from status output).
For each conflicted file:
- Open the file and understand the surrounding code and intent.
- Prefer minimal, mechanical conflict resolutions:
  - Keep upstream changes unless the feature branch deliberately supersedes them.
  - Re-run generators (lockfiles, codegen) instead of hand-editing when appropriate.
- If intent is ambiguous, ask a single targeted question, for example:
  - "Should we keep the new upstream behavior X, or keep the feature behavior Y?"
  - "Is this file generated and safe to regenerate, or do you want manual resolution?"
Apply the resolution, then stage only resolved files:
- ```
git add <file...>
```
Continue:
- ```
git rebase --continue
```
If you reach a point where resolution is too risky/unclear:
- Stop and ask; optionally propose aborting the rebase.

Helpful commands during conflicts:

Inspect current conflict hunks:
```
git diff
```
See the commit being replayed:
```
git show
```
If you need to back out:
```
git rebase --abort
```
(this is safe and should be preferred over destructive resets)

当发生冲突时：

收集上下文：
- ```
git status
```
- 从状态输出中识别冲突文件。
针对每个冲突文件：
- 打开文件，理解周边代码和意图。
- 优先采用最小化、机械化的冲突解决方案：
  - 保留上游变更，除非特性分支明确要覆盖这些变更。
  - 合适的情况下重新运行生成器（锁文件、代码生成），而非手动编辑。
- 如果意图不明确，提出单个针对性问题，例如：
  - "我们应该保留上游的新行为X，还是保留特性的行为Y？"
  - "这个文件是生成的，可以安全重新生成，还是你需要手动解决冲突？"
应用解决方案，然后仅暂存已解决的文件：
- ```
git add <file...>
```
继续：
- ```
git rebase --continue
```
如果你认为解决方案风险太高/不明确：
- 停止并询问；可以提议中止变基。

冲突期间的实用命令：

检查当前冲突块：
```
git diff
```
查看正在回放的提交：
```
git show
```
如果你需要退出：
```
git rebase --abort
```
（这是安全的，优先选择它而非破坏性的重置操作）

7) Post-rebase verification

7) 变基后验证

Show the new commit range:

git log --oneline --decorate origin/{base_branch}..HEAD

Run appropriate repo checks (tests, typecheck, lint) if available.

显示新的提交范围：

git log --oneline --decorate origin/{base_branch}..HEAD

如果仓库有对应的检查项，运行检查（测试、类型检查、lint检查）。

8) Push updated branch (requires confirmation)

8) 推送更新后的分支（需要确认）

If the branch already exists on origin, rebasing rewrites history, so pushing requires force-with-lease.

Print the exact command and wait for confirmation:

git push --force-with-lease origin HEAD:{branch_name}

如果分支已经存在于上游，变基会修改历史，因此推送需要使用force-with-lease。

打印准确的命令并等待确认：

git push --force-with-lease origin HEAD:{branch_name}

Recovery

恢复

If something goes wrong, use
```
{backup_ref}
```
to restore the pre-rebase state.
Do not run destructive commands (e.g.,
```
git reset --hard
```
) unless I explicitly confirm after you show the exact command.

如果出现问题，使用
```
{backup_ref}
```
恢复变基前的状态。
除非你展示准确命令后我明确确认，否则不要运行破坏性命令（例如
```
git reset --hard
```
）。