smooth-rebase

平滑变基

将当前分支变基到仓库的默认分支上，并在过程中解决冲突。保留原有意图，避免默默猜测；如果代码或上下文不足以明确支持正确的解决方案，请询问用户。

行为

此技能遵循一条简单规则：

1. 如果变基已在进行中（存在冲突或已暂停），不要开始任何新操作。解决当前冲突，继续变基，并重复此过程，直到变基完成。
2. 否则，检测仓库的默认分支（main、master 或远程声明的其他分支），获取该分支，并将当前分支变基到其上，解决过程中出现的任何冲突，直到变基完成。

适用范围

当用户希望让分支保持最新状态或完成有冲突的变基时，使用此技能，包括以下请求：

• “变基此分支”
• “变基到 main”
• “解决 PR 冲突”
• “继续变基并解决冲突”

如果用户明确指定了其他基准分支，则变基到该分支，而不是默认分支。

规则

• 保守处理。不要盲目选择一方。
• 将冲突解决视为语义合并任务，而非文本编辑任务。
• 如果双方内容互为补充，优先保留双方内容。
• 如果正确的处理方式取决于产品意图、架构方向、归属关系或命名／结构约定，请询问用户。
• 如果基准分支更改了结构，而功能分支更改了内容，不要假设哪一方优先。检查双方内容；如果答案不明显，请询问用户。
• 除非能说明代码已过时或不正确，否则不要丢弃代码。
• 确保最终文件保持一致、可编译，并符合周围代码的风格。
• 切勿将默认分支变基到自身；如果当前分支就是默认分支，请停止并告知用户。
• 如果开始变基前工作区存在未提交的更改，请停止并询问用户如何处理。不要使用 git stash。
• 变基会重写历史，因此之后如果需要推送，请使用 git push --force-with-lease，绝不要使用普通的 --force。

何时询问用户

如果任何冲突存在以下不确定性，请停止并询问：

• 基准分支引入了新的结构、抽象或文件布局
• 功能分支中的业务逻辑不再能干净地适配新结构
• 双方以不同方式更改了相同逻辑
• 一方重命名或移动了代码，而另一方更改了其行为
• 任一方可能体现了较新的产品决策或 API 契约
• 冲突涉及生成文件、锁文件、迁移或大型重构，而团队对此类变更的处理策略可能不同

可以询问的问题示例：

• “我应该保留 main 中的结构，并将此分支的行为移植到其中吗？”
• “这看起来是一方重命名，另一方更改逻辑。你希望将两者结合起来吗？”
• “基准分支删除了这段代码，但此分支扩展了它。删除是有意的吗？”

工作流

1. 确定当前状态

检查是否已有变基（或其他存在冲突的操作）在进行中：

git status
ls .git/rebase-merge .git/rebase-apply 2>/dev/null

• 变基进行中 → 跳到第 3 步并继续变基。
• 合并或 cherry-pick 进行中 → 按照下文所述的同等谨慎程度解决冲突，然后使用与该操作对应的继续命令完成操作（git merge --continue 或 git cherry-pick --continue），而不是 git rebase --continue。
• 状态干净 → 继续第 2 步。

如果工作区有未提交的更改且没有正在进行的变基，请停止并询问用户如何处理。不要暂存更改。

2. 检测默认分支并开始变基

通过 git 检测默认分支，不要假定分支名称：

git symbolic-ref --short refs/remotes/origin/HEAD

如果该引用未设置，请先解析：

git remote set-head origin --auto

或者，作为备用方案，直接从远程读取：

git ls-remote --symref origin HEAD

然后获取并变基：

git fetch origin
git rebase origin/<default-branch>

如果变基完成且没有冲突，请报告成功并停止——无需执行其他操作。

3. 一次处理一轮冲突

每次变基因冲突而暂停时，先找出发生冲突的文件：

git status --short
git diff --name-only --diff-filter=U

对于每个发生冲突的文件：

• 阅读工作树中的冲突标记
• 检查文件周围的内容，了解结构和意图
• 如有需要，检查 base、ours 和 theirs 版本
• 查看附近引用了冲突符号的代码

git show :1:path/to/file
git show :2:path/to/file
git show :3:path/to/file

变基期间请记住，阶段 2（ours）是变基的 base 分支，也就是当前分支要变基到的分支；阶段 3（theirs）是正在重放的当前分支提交。这与合并时的直觉相反。此技能启动变基时，base 是默认分支；若恢复已经开始的变基，请根据 git status 输出（“rebasing onto ...”）或 .git/rebase-merge/onto 确认 base，不要假定它是默认分支。

4. 对每个冲突进行分类

对于每个文件或代码块，判断冲突属于哪种类型：

• 结构与内容 — 一侧重新组织了代码，另一侧更改了逻辑
• 并行逻辑修改 — 双方在重叠的代码行中都更改了行为
• 重命名／移动与编辑 — 一侧移动了代码，另一侧修改了代码
• 删除与修改 — 一侧删除了代码，另一侧更新了代码
• 机械性冲突 — 导入、格式、生成的部分、锁文件

机械性冲突通常可以直接解决。 语义冲突需要更有力的依据，通常应询问用户。

5. 只解决明确的冲突

只有在上下文有充分依据支持正确结果时，才可不经询问直接解决，例如：

• 重复导入或简单的排序冲突
• 双方的内容可以安全地合并
• 一侧明显已过时或已被机械性地取代
• 移动／重命名显而易见，且可以干净地移植行为变更

解决时：

• 保留所有必要行为
• 除非冲突变更明确地取代了当前架构，否则保留当前架构
• 重新编写整合后的结果，使其简洁清晰，而不是逐行拼接带冲突标记的代码

如果有一个或多个代码块无法明确解决，请暂停并说明：

• 冲突文件
• 双方内容的简短说明
• 你认为双方各自想实现什么
• 需要用户作出的具体决定

问题应具体明确，便于用户作出决定。

6. 继续变基，直到完成

解决当前这一轮的所有冲突后：

• 确认不再有冲突标记
• 使用 git add 暂存已解决的文件
• 继续变基：

git rebase --continue

对每一轮冲突重复步骤 3–6，直到变基完成。除非用户要求，否则不要中止变基。

7. 完成收尾

变基完成后：

• 确认分支历史正常（git log --oneline <base>..HEAD，其中 <base> 是执行变基时基于的分支）
• 如果用户要求更新远程分支，请使用带租约保护的方式推送：

git push --force-with-lease

除非用户要求推送，或任务明确需要推送（例如，解决 PR 冲突），否则不要推送。

解决冲突的启发式规则

以下情况优先合并双方内容：

• 一侧更改了 API 结构，另一侧更改了使用同一概念的行为
• 双方所做的导入、依赖项或注册都不可或缺
• base 中新增的封装或抽象可以干净地承载分支特定逻辑

以下情况优先采用 base 分支的结构：

• base 在附近多个文件中引入了更全面的重构
• 可以毫无歧义地将功能分支的代码移植到新结构中
• 保留旧结构会重新引入过时模式

以下情况优先采用功能分支的内容：

• 其中包含正在审查的功能或修复
• base 一侧的更改大多是机械性的，可以整合到周围代码中
• 丢弃该内容会在不知不觉中移除分支原本要实现的行为

这些只是启发式规则，并非自动适用的规则。有疑问时请询问。

输出格式

对于每个存在冲突的文件，请总结：

• file
• conflict type
• decision
• reason
• needs user input（yes 或 no）

如果要询问用户，请以简短的编号列表列出你需要用户决定的事项。

故障排除

• 如果仍有冲突标记，请先搜索 <<<<<<<、======= 和 >>>>>>>，再继续。
• 如果在变基期间不清楚各阶段的含义，请检查文件内容和提交历史，不要依赖假设。
• 如果缺少 refs/remotes/origin/HEAD，请在检测默认分支前运行 git remote set-head origin --auto。
• 如果解决冲突后某个提交变为空，请对该提交使用 git rebase --skip——其更改已存在于基础分支中。
• 如果锁文件或生成文件发生冲突，仅当项目有明确的标准工作流程且结果具有确定性时，才优先重新生成。
• 如果一侧删除了文件，另一侧修改了文件，不要猜测删除是否出于本意；请检查附近的代码，如仍不明确则询问用户。
• 如果必须完全撤销变基，git rebase --abort 会恢复分支的原始状态——但只有在用户提出要求时才这样做。