resolve-merge-conflicts

步骤 1 — 检测基分支

堆叠式 PR 的目标是另一个功能分支，而不是 main。如果合并 main，GitHub 上的冲突不会改变。

在仓库根目录中，确定基分支：

gh stack view

如果当前分支有未关闭的 PR，请确认基分支：

gh pr view --json baseRefName,mergeable,mergeStateStatus

• baseRefName 不是 main → 堆叠式。基分支就是该分支（在 gh stack view 中位于此 PR 下方的父 PR）。
• 没有 PR，或 baseRefName 是 main → 基分支是 main。

将基分支名称记录为 <base>。

检查整个堆栈是否线性。GitHub 要求每个分支都直接位于其下方分支的最新提交之上。gh stack view 会用 ⚠ 标记断开的链接。即使 PR 状态为 MERGEABLE，堆栈仍可能显示“branches have diverged”。

如果有任何链接断开，先修复下游分支（先父分支，再子分支）。如果较低层的分支跳过了其父分支（例如 petal-components 缺少 admin-search-lookups 中的某个提交），则必须先变基并推送该分支，再变基其上方的分支。只变基顶层分支会留下重复提交和分歧横幅。

同步整个堆栈时，请一次处理一个分支，重复执行步骤 2–7：先将每个分支变基到已更新的父分支上，再推送，然后再处理上方的分支。

范围 — 仅当前分支

仅处理当前检出的分支。与 <base> 同步，解决其中的冲突标记，完成变基或合并，然后推送。

步骤 2 — 与基分支同步

获取基分支，然后进行同步。对于堆叠式分支，变基到父分支上；对于基于 main 的分支，合并 main。

堆叠式（<base> 不是 main）：

git fetch origin <base>
git rebase origin/<base>

非堆叠式（<base> 是 main）：

git fetch origin main
git merge origin/main

如果同步顺利完成，跳到步骤 5。如果变基或合并仍在进行且存在冲突，请继续步骤 3。

步骤 3 — 查找冲突

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

阅读每个文件中的冲突标记（<<<<<<<、=======、>>>>>>>），并了解双方各自做了哪些更改。变基期间，ours 是基分支（<base>）；theirs 是正在重放的提交。

步骤 4 — 解决冲突或告知用户

对于每个冲突，请作出判断：

自动解决：双方的行为都可以保留，例如双方添加了不同的导入、别名或子句；同一文件中互不重叠的新增内容；一方调整格式，而另一方在其他位置修改逻辑。合并双方的更改，移除标记，并暂存文件。

告知用户：遇到真正的冲突时，例如同一行为有不同实现方式；一方删除或重命名了另一方仍依赖的内容；或者合并双方会改变运行时语义。不要猜测。停止并报告：

• 文件路径和大致位置
• <base> 的行为与当前分支的行为
• 为什么两者无法共存，且必须选择其中一种行为

如果仍有任何真正的冲突，不要完成同步。询问用户如何继续。冲突解决前，请跳过步骤 5–7。

自动解决所有冲突后：

git add <resolved-files>

然后完成正在进行的操作：

• 变基： git rebase --continue
• 合并： git commit --no-edit

步骤 5 — Doctor

查找、阅读并遵循 doctor 技能。仅当失败是由冲突解决或当前分支差异中的更改直接导致时，才修复失败。如果某项失败需要修改由下游 PR 负责的内容，则超出范围 — 报告该问题，然后继续推送，除非用户另有要求。如果失败反映了同步过程中尚未解决的语义选择，请停止并报告给用户，不要猜测。

步骤 6 — 提交并推送

检查是否存在未提交的更改（doctor 修复、尚未提交的冲突解决等）：

git status --short

如果有暂存或未暂存的更改，请提交，并使用能体现工作内容的提交消息（例如，变基冲突解决、doctor 修复）。

推送分支。变基会重写历史，因此堆叠式分支需要使用 lease 推送：

# after rebase (stacked branch)
git push --force-with-lease

# after merge (main-based branch)
git push -u origin HEAD   # use -u when there is no upstream yet; otherwise plain git push

Doctor 检查通过且所有预期更改均已提交之前，不要推送。

步骤 7 — 在 GitHub 上验证

确认 PR 和堆栈状态正常：

gh pr view --json mergeable,mergeStateStatus
gh stack view

mergeable 应为 MERGEABLE。堆栈中的任何分支都不应出现 ⚠。mergeStateStatus 为 BLOCKED 可能表示 CI 或审核要求尚未满足，并非合并冲突。

注意事项

• 除非用户要求，否则绝不要重置或中止变基／合并。
• 仅使用 CLI 进行变基（git rebase origin/<base>）。绝不要打开 GitLens 交互式变基，也不要运行 git rebase -i。
• 如果可以安全组合，优先保留双方的意图，而不是只选择一方。
• 如果同步失败的原因不是冲突（例如未提交的更改阻止了同步），请先修复问题或报告情况。
• gh stack rebase 会对整个堆栈进行变基，且可能在最顶层分支失败。遇到这种情况时，按从下到上的顺序手动对每个出问题的分支进行变基，使用 --force-with-lease 推送每个分支，然后再对上一个分支进行变基。