---
name: git-commit
description: 起草、创建或汇报 Angular-style 本地 Git 提交。用于明确的提交交付；分支集成使用 worktree-rebase-merge，不 push。
---

# Git 提交流程

以经范围校验的 staged diff 创建本地提交。只读预览可使用尚未暂存的候选，
但必须标为草稿。`<git-commit-skill-dir>` 指实际加载的本 Skill 目录。

## 任务与边界

| 任务 | 结果 |
| --- | --- |
| 起草或预览 | 根据 staged 内容或获准候选返回草稿，不改变 Git。 |
| 创建提交 | 在有效提交授权下完成范围判断、预览、暂存、提交和校验。 |
| 汇报已有提交 | 读取指定提交或范围的真实消息与统计，不启动新提交。 |
| 为组合 Skill 推导分支名 | 只返回合法候选，不暂存、提交或创建分支。 |

本 Skill 不运行 `git push`、rebase 或 merge。调用方传入真实任务、允许范围和已有证据，
不需要采用本 Skill 的内部字段。

## 选择模式

- **只命名或汇报已有提交**：只完成该任务；未指定提交对象时先明确对象。
- **仅预览、起草或只读**：不暂存、不创建消息文件、不提交。已有 staged 内容时
  只用其起草；索引为空时使用获准范围内的候选。
- **确认模式**：展示完整预览并等待批准。未单独获准时，确认前不暂存。
- **默认模式**：明确调用本 Skill 或宿主已授权自动本地提交时，展示预览后直接提交。

用户的禁止、范围、确认和暂缓要求持续有效；“不提交”不自动授权暂存。

## 范围与 Git 状态保护

1. 记录调用目录，使用 `git rev-parse --show-toplevel` 定位仓库根目录；相对路径先按原调用目录解析。
2. 读取 HEAD、分支、status、最近提交、staged/unstaged raw diff 和相关 untracked 内容，
   区分用户已有变更与本任务候选。
3. 准备写入时复验 HEAD、索引、候选路径和内容。发现冲突、归属不明或非预期漂移时
   停止，不覆盖、清理或自动 amend。
4. 获准后只执行一次选定的暂存动作，并比较 staged paths 与 raw patch 是否与候选完全一致。
   不一致时停止，不通过第二次 `git add` 修正范围；不创建空提交。

| 情况 | 暂存动作 |
| --- | --- |
| 已有索引 | 不运行 `git add`，只提交既有 staged 内容；超出请求范围时停止。 |
| 显式交付、空索引、限定路径 | 一次 `git add -- <selected-paths>`。 |
| 显式交付、空索引、未限定路径 | 未禁止暂存且非 staged-only 时，在仓库根目录一次 `git add .`。 |
| 宿主授权自动提交 | 一次 `git add -- <expected-commit-paths>`，禁止 `git add .`。 |

宿主自动提交还必须有首次写入前的 HEAD、初始 Git 状态、允许路径和内容归属证据。
初始索引非空、唯一暂存前出现非 Agent staged 内容、验证失败或仍有暂缓要求时，
停止自动提交。这不反向限制用户已明确授权的 staged-only 提交。

## 提交主流程

1. 起草提交时读取 [提交信息契约](references/commit-message.md)。在主对话以 `text` 代码围栏展示
   完整、将要使用的消息；仅预览到此结束，确认模式等待批准。
2. 完成唯一暂存并复验后，将与预览完全一致的内容写入本任务专用消息文件。
   候选或消息变化时重新审核和展示；用户要求确认时不复用旧批准。
3. 使用 Skill 内校验器检查消息，再运行 `git commit -F <message-file>`。
4. 以新建完整 commit hash 执行提交后消息一致性校验。校验失败时保留消息文件，
   不 amend，不声称交付完成。
5. 校验通过后删除本任务消息文件，读取 [统计与提交回执](references/reporting.md)，根据 Git 真实结果交付。

仅为 `submit-pr` 或 `worktree-rebase-merge` 推导分支名时，读取
[分支命名](references/branch-naming.md)，不进入提交流程。

## 完成与停止条件

只有范围与 staged raw patch 一致、必要验证通过、Git 真实消息与预览一致，且最终
状态和统计已核对时，才算创建提交完成。范围无法证明、出现冲突或漂移、权限被拒、
提交前/后校验失败、hook 改写结果或统计不一致时保留现场并报告具体阶段，
不自动扩大暂存、重试写入、amend 或清理用户状态。