git-commit

使用 Conventional Commits 编写 Git 提交信息

我会阅读实际差异，确定类型、范围和说明。我绝不会凭任务记忆编写提交信息。

仅生成提交信息模式

当我被要求提供提交信息，例如“给我一条提交信息”或“推荐一条提交信息”，而不是被要求执行提交时，我会照常分析差异，并输出两个可用版本：单行版和详细版。

工作流

1. 分析差异

git diff --staged        # if files are staged
git diff                 # if nothing staged
git status --porcelain

编写提交信息前，我会将 git status --porcelain 中的每个文件准确归入一个提交。混合差异会拆分成多个提交，而不是写成一条含糊的提交信息。

2. 暂存文件

我只暂存自己在差异中读过的文件。.env、credentials.json 和密钥文件会保持未暂存状态。

当调用方提供已验证的内容快照时，我会记录分支、旧 HEAD 和原始索引树，然后在该 HEAD 上的临时分离工作树中构建候选提交。我会将已验证的树加载到该工作树的索引和文件中，要求 git write-tree 与快照一致，并在那里执行常规提交，以确保所有钩子仍会运行。我要求候选提交的 HEAD^{tree} 与快照一致。钩子执行失败或内容不匹配时，实际分支不会受到影响。

在触碰实际分支前，我会根据候选提交准备一个隔离的替代索引，并要求其树与快照一致。只有在候选提交和替代索引都准备完毕后，我才会独占获取实际索引锁。持有锁期间，我会将实际索引复制到隔离路径，并要求其树与记录的原始索引树一致。不匹配时，我会释放锁，实际分支不会受到影响。我会将记录的分支从记录的旧 HEAD 原子性地推进到候选提交，将准备好的索引字节写入持有的锁中，要求被锁定的索引树与快照一致，并在不更改工作树的情况下，将其原子性地安装为实际索引。我会在所有情况下释放锁并移除临时工作树。如果分支推进后索引安装或回读失败，我会报告 branch advanced / index not refreshed，并附上分支、候选提交、记录的索引树和恢复命令。我绝不会重试分支切换，也不会隐瞒部分完成的状态。我绝不会在钩子或其他 Git 命令仍需要实际索引锁时获取该锁、在实际分支上创建候选提交，或重新暂存实时工作树。

3. 生成提交信息

我会从差异中读取类型、范围（即受影响的区域或模块）以及说明。

我会让主题使用祈使语气、不超过 72 个字符，并着重说明原因（WHY），而不是内容（WHAT）。差异本身已经展示了具体内容。正文使用 - 项列出关键变更，最多 3 到 5 项。

我会为一年后运行 git log 的人编写提交信息。我不会在其中使用 em dash 或 en dash。安装 unslop 后，其余规则由它负责。

4. 提交

# Single line
git commit -m "<type>[scope]: <description>"

# Multi-line: one quoted -m string, newlines inside the quotes
git commit -m "<type>[scope]: <description>

<optional body>

<optional footer>"

每个提交只包含一项原子性变更。

这里的每项 Git 操作都只会追加。如果钩子执行失败，我会暂存、提交，并修复问题后在其基础上创建新提交，而不是修改已有提交。

有四件事不在“只追加”的范围内，我会明确说明。我不会更改 git config；我会让钩子正常运行，不使用 --no-verify；未经明确请求，我不会使用 --force 或硬重置；我绝不会强制推送 main。