git-commit-organizer

Git Commit Organizer

将杂乱的工作树整理成清晰、易读的提交历史。良好的提交历史能帮助后续所有人：每个提交都是独立、完整的原子提交，便于审查、回滚和 cherry-pick。此技能正是为此而设，而且绝不会擅自提交或推送。始终由你先行确认。

可传入的选项（均为可选）

可从任何语言的自然语言中识别这些选项；根据意图执行，而不是拘泥于具体措辞。

选项	默认值	用户可能的说法
gitmoji	关闭	“带上 gitmoji”、“添加表情符号”
issue	自动从分支检测	“#412”、“用于 issue 412”、“没有 issue”
exclude	不排除	“不包含 docs 文件夹”、“跳过 vendor/”

工作流

1. 查看实际发生的更改

git status
git diff --stat
git diff --cached --stat

然后读取相关文件的实际差异（git diff <file> 和 git diff --cached <file>）。仅凭文件名无法判断更改属于功能、修复还是重构——要看差异。你要按意图分组，因此需要理解这些意图。

2. 检测 issue 引用（可选）

开始时运行 git branch --show-current——绝不要假设分支与之前对话中相同，因为用户可能已经切换分支。如果分支名明显包含标识符（常见格式：feature/412、412-add-search、fix/PROJ-42），则提出将其作为 #412 / PROJ-42 纳入提交信息。只有用户提出要求，或分支名明显包含 issue 标识符时，才附加 issue。绝不要编造 issue 编号；如果用户提到了你找不到的编号，请询问。

3. 应用排除项

默认情况下，提交 Git 已纳入管理的所有内容（已跟踪的更改和新文件）；.gitignore 是忽略规则的事实来源。只有用户提出要求时才跳过路径——此时让这些文件保持未暂存状态，不要删除或修改它们。

4. 将更改分组成原子提交

每个提交对应一项逻辑更改。目标是让每个提交都能独立成立，且不会导致构建失败。以下是一些有用的分组方式：

• 更改及其对应测试应放在一起。
• 不相关的错误修复和新功能应分别提交。
• 配置、构建和依赖项更改适合归为一组。
• 纯格式调整（空白、导入顺序）不要与行为更改放在同一个提交中。
• 大规模重命名或移动通常应单独提交，与编辑分开。

如果所有更改确实属于同一项连贯的工作，那么单次提交就是正确选择——不要为了拆分而过度拆分。如果计划创建多个提交，或分组方式存在任何歧义，请先展示拟定的分组并征求确认，再进行任何操作。

5. 选择类型和范围

类型	适用场景
feat	新功能
fix	错误修复
refactor	不改变行为的结构调整
perf	性能改进
test	添加或更新测试
docs	仅修改文档
style	仅调整格式，不更改逻辑
build	构建系统或依赖项
ci	CI/CD 配置
chore	不属于其他类别的维护工作
revert	撤销先前的提交

范围为可选项：受影响的区域（功能、模块或目录），应简短且使用小写。

6. 编写提交信息

格式：type(scope): [#issue] 简短描述

• 标题——使用祈使语气（“add”，而不是“added”），首词首字母大写，不加句末标点，尽可能控制在约 72 个字符以内。
• 正文（可选；但如果仅凭差异无法看出 原因，则应包含）——空一行后，以 - 开头的项目符号句子描述更改内容及原因。避免写“更新了导入”之类的无关内容。
• gitmoji（仅在启用时）——根据此映射为标题添加前缀：feat ✨ · fix 🐛 · refactor ♻️ · perf ⚡ · test ✅ · docs 📝 · style 🎨 · build 📦 · ci 👷 · chore 🔧 · revert ⏪

7. 提出方案，然后等待批准

提交前务必先展示计划，并等待明确答复同意。 对于每个计划的提交，都要说明提交说明和将要暂存的确切文件。意外提交很难撤销，也会损害信任，因此这条门槛是绝不可变通的规则。

8. 暂存并提交

只暂存该组对应的文件，然后提交。对于多行提交说明，使用 heredoc，以确保正文的格式保持完整：

git add <specific files for this commit>
git commit -m "$(cat <<'EOF'
type(scope): #412 Short description

- What changed and why.
- Another meaningful detail.
EOF
)"

每次提交后显示 git log -1，让用户查看结果。

9. 确认结果

所有提交完成后，运行 git log --oneline -n <number of commits>，以便一目了然地查看新增的历史记录。

硬性规则

• 绝不推送。 是否推送始终由用户决定。无论如何都不要运行 git push。
• 未经明确批准，绝不提交（见第 7 步）。
• 不得标注 AI 或工具署名。 提交代表项目的人类作者。绝不添加 Co-authored-by、Signed-off-by，也不得添加任何提及 AI 工具的尾注、页脚或文本。
• 英文、祈使语气、原子化。

示例

此处的作用域（search、parser、http、readme）有意采用通用名称——请使用仓库实际使用的领域名称。

示例 1 — 单项功能（Web 应用），无选项

更改内容：一个搜索组件及其测试。

feat(search): add fuzzy matching to the product search box

- Match results by approximate spelling so small typos still return hits.
- Cover the ranking edge cases with unit tests.

示例 2 — 将无关工作拆分为两次提交（命令行工具）

工作区中有一个错误修复和一次依赖升级。

fix(parser): stop crashing on an empty config file

- Treat a missing or empty config as the defaults instead of throwing.

chore(deps): upgrade the HTTP client to 4.2.0

示例 3 — 根据分支 412-retry-logic 自动检测 gitmoji 和问题编号（库）

♻️ refactor(http): #412 extract retry handling into its own module

- Move the backoff logic out of the client so it can be unit-tested in isolation.

示例 4 — 仅修改文档

docs(readme): document the new --watch flag

不适用情形

• 编写或修改代码（这是实际工作；此技能会在之后提交更改）。
• 解决合并冲突。
• 创建或描述拉取请求/合并请求。
• 任何远程操作——尤其是推送，绝不是此技能的职责。