recommit

重新整理提交

将分支合并基点之后的提交重写为一组各自讲述一个故事且独立完整的提交。保留最终提交树。此技能用于重塑历史，不会编辑代码。

请勿使用此技能来更改行为、重写目标分支已包含的提交，或在未经协调且其他人依赖的分支上使用。

约定

• 开始和结束时，Git 可见的工作树都必须干净。
• 只重写已确认合并基点之后的提交。
• 保留原始分支顶端的精确提交树。
• 重写前展示拟议的提交序列和恢复点。

工作流

0. 锁定安全范围

要求指定分支名，且 Git 可见的工作树干净：

git branch --show-current
git status --porcelain=v1 --untracked-files=all

如果分支名为空或状态输出不为空，则停止。干净的初始状态可确保记录的分支顶端是完整的恢复点。如果工作树因审查修复尚未提交而不干净，请告知用户，git commit --fixup=<sha>，或在已安装时使用 git absorb，会将这些修复变成此技能可折叠的 fixup! 提交。

如果有 PR 或 MR 跟踪器元数据，则根据该元数据确定目标分支；如果存在远程仓库，则刷新其远程跟踪引用。没有跟踪器元数据时，使用 origin/HEAD。只有当这些来源不存在或相互冲突时，才询问用户。

验证目标并记录以下值：

git rev-parse --verify <TARGET_REF>^{commit}
git rev-parse HEAD
git rev-parse HEAD^{tree}
git merge-base <TARGET_REF> HEAD

将目标引用称为 TARGET_REF，将输出称为 ORIG、ORIG_TREE 和 MERGE_BASE；在后续命令中使用记录的字面值，以便它们在不同工具调用之间保持有效。检查范围形状（第 1 步会读取完整差异）：

git log <MERGE_BASE>..<ORIG> --oneline
git diff <MERGE_BASE>..<ORIG> --stat

当目标已知、范围非空、初始状态干净，且四个记录值均可用时，此步骤完成。

1. 设计提交序列

阅读 MERGE_BASE..<ORIG> 的完整差异和现有提交。然后按顺序写出拟议的提交。对于每个提交，说明其标题、负责的文件或代码块，以及用于验证它的检查。

• 每个提交只包含一个连贯目的，且可独立构建和测试。
• 将保留行为的准备工作放在使用该准备工作的行为之前。让改动更容易实现的重构应先提交。
• 独立成立的改进应单独提交。不依赖功能也有充分理由的错误修复或 UX 修复，更容易单独审查和回退。
• 基础设施应与首个使用它的改动放在一起。没有任何调用方的机制一经提交便成了无用代码。
• 先提交依赖项，再提交使用它的改动。
• 将生成文件（锁文件、翻译、快照）与需要它们的改动放在一起。
• 如果拆分会导致任一提交无效，则合并这些改动。人为拆分和杂项拼盘同样不可取。

当每个改动路径和代码块都恰好归属一个拟议提交，且每个拟议提交都有验证命令或明确说明为何不需要验证时，此步骤完成。

2. 展示计划

展示已确认的目标、MERGE_BASE..<ORIG>、完整的拟议提交序列，以及恢复命令 git reset --hard <ORIG>。重写只会更改本地历史，且该命令即可撤销，因此无需等待即可继续。

3. 重建历史

阅读 REBUILD.md，并使用与拟议序列相匹配的方法。当本地历史与拟议序列一致且所有最终改动均已提交时，此步骤完成。

4. 验证结果

检查 Contract 中的状态不变量：

test "<ORIG_TREE>" = "$(git rev-parse HEAD^{tree})"
test -z "$(git status --porcelain=v1 --untracked-files=all)"

然后使用 REBUILD.md 中的临时工作树流程，对 MERGE_BASE..HEAD 中的每个提交运行计划的检查。较晚提交中的剩余更改不得在较早提交的检查期间可见。

如果不变量或检查失败，使用 git reset --hard <ORIG> 恢复到干净的起始状态，确认状态干净，并报告失败的检查。 恢复操作会还原已记录的起始状态，因此无需单独许可。

只有不变量和所有计划的逐提交检查都通过后，此步骤才算完成。

5. 完成

显示 git log <MERGE_BASE>..HEAD --reverse --oneline、保存的 ORIG，以及通过的检查。

示例

一个“Language setting”PR 包含两个提交：一个 _create_combo 重构提交，接着是一个捆绑了通用对话框自动调整大小优化、note 标题机制，以及包含 20 个生成的翻译文件的语言功能的杂项 feat 提交。计划的顺序如下：

1. refactor(settings): extract _create_combo 包含保持行为不变的准备工作。
2. feat(settings): fit the dialog height to the active tab 包含独立的 UX 修复，并通过累积式暂存补丁拆分出来。
3. feat: add a Language setting 包含该功能、note 机制（此前没有任何内容使用它），以及生成的翻译文件。

最终树与 ORIG_TREE 相符，且每个提交都在临时工作树中通过了 lint 和类型检查。