git-squash

Git Squash

如果这些说明已通过斜杠或美元符号调用出现在对话中，请直接遵循；不要再次通过技能工具调用此技能。

将当前功能分支压缩为一个提交，用于表示相对于解析出的默认分支的净变更。

参数

• --subject <line>：要求替换后的提交消息第一行必须与此内容完全一致。
• --base <branch>：覆盖默认分支检测结果。

如果未提供 --subject，Agent 会根据仓库的消息格式，为保留的净差异撰写主题。如果未提供 --base，辅助程序会依次解析 origin/HEAD，然后查找本地或远程的 main、master 或 trunk。

计划接口

从此 SKILL.md 中解析辅助程序。将其 JSON 写入仓库外的临时路径，以确保预检保持干净：

uv run "<skill-dir>/scripts/git-squash.py" plan \
  [--cwd <repo>] [--base <branch>] [--subject <line>] > <plan.json>

plan 为只读操作。它会验证 Git 工作区、已关联的分支、干净的工作区和索引、已解析的基准分支、当前分支非默认分支、合并基点、超前提交数为正，以及远程状态。它会返回 schemaVersion: 1、不可变的原始 HEAD、合并基点、基准引用、按时间顺序排列的提交、唯一作者、树和远程状态，以及回滚信息。如果前置条件未通过，则会退出且不更改历史记录。

变更前，请用简洁的纯文本表格展示分支、基准引用、合并基点、被替换的提交、工作区状态、远程状态和回滚 HEAD。

由 Agent 编写提交消息

检查计划中的提交，以及 mergeBase..originalHead 范围内的净差异。净差异是权威依据；中间提交仅用于了解意图和署名信息。如果摘要含义不明确，请检查相关代码块。

如果提供了 --subject，请原样使用。否则，请读取 <git-root>/.agents/commit.toml 中 [message] 下的 format；其值为 natural 或 conventional。如果文件或键不存在，则默认为 conventional。

• natural：撰写自然语言的祈使句主题，不带类型前缀，例如 Add retry to webhook delivery。
• conventional：根据保留变更的结果选择类型：feat、fix、refactor、docs、test、build、ci、chore(deps)、style、perf、revert、ai 或 chore。不要仅仅因为这是一次 squash 就将变更归为 chore。前缀后面的主题内容使用小写。

主题应采用祈使句，具体明确，且末尾不加句号。最多添加五条正文要点，分别描述不同的保留成果；如果主题已足够清楚，则省略正文。不要罗列路径或统计信息。为计划中除当前 Git 用户之外的每位作者添加一条 Co-authored-by: Name <email> 页脚。所有语义表述均由 Agent 负责，并且必须确保每项陈述都有净差异作为依据。

将最终消息写入仓库外的临时文件。

应用接口

uv run "<skill-dir>/scripts/git-squash.py" apply \
  --plan <plan.json> --message-file <message.txt>

apply 会将重写操作绑定到计划中的原始 HEAD、分支、合并基点、基准引用、干净状态、回滚索引以及可选主题。它会在变更前立即重新验证这些信息；如果计划已过期，则会失败且不更改历史记录。它会软重置到合并基点，验证暂存的净差异非空，然后使用消息文件提交。

如果变更后、替换提交完成前有任何操作失败，辅助程序会恢复原始 HEAD 和精确索引。它不会改动工作区文件。不要手动重现重置或回滚流程；如果辅助程序失败，在检查其诊断信息和当前 Git 状态之前，不要继续操作。

报告

成功后，报告计划中被替换的提交数、已解析的基准引用、新哈希和主题。如果该分支存在于 origin 上，请明确给出下一步操作 git push --force-with-lease；除非得到明确请求，否则不要执行。

开头使用 ### ✅ Squashed — <old count> commits → 1。预检事实、哈希、命令、错误和回滚说明均须保持简洁准确。