human-commit

Human Commit

读取 Git 更改，并生成听起来像真实开发者写出的提交消息。

工作流

步骤 1 — 阅读差异

git diff --cached 2>/dev/null

如果输出为空（没有暂存内容），则改用：

git diff HEAD 2>/dev/null

还要检查涉及哪些文件：

git status --short 2>/dev/null

如果差异超过约 500 行，不要尝试直接分析原始内容。先找出更改最多的文件：

git diff --cached --stat 2>/dev/null || git diff HEAD --stat 2>/dev/null

然后重点分析更改最多的文件和整体主题，而不是逐行分析。

步骤 1b — 检测仓库的提交风格

git log --oneline -5 2>/dev/null

查看最近 5 条提交。如果大多数遵循 Conventional Commits 格式（type(scope): subject 或 type: subject），则仓库使用 CC。如果它们是全小写的普通句子，则采用普通风格。匹配现有风格，不要引入新风格。

步骤 2 — 分析更改

识别：

• 更改了哪些文件，以及涉及哪个领域（身份验证、UI、依赖项、配置、测试等）
• 更改的性质（修复、添加、删除、移动、更新、重构）
• 是否有明显的“原因”（Bug、清理、新功能、维护）
• 范围（针对单体仓库）：如果更改的文件位于 packages/、apps/ 或命名的工作区下，请根据目录名称推断范围（例如，packages/auth/ → 范围 auth）
• 破坏性更改：如果差异删除了导出函数、重命名了公共接口、更改了函数签名或提升了主版本号，请标记出来——提交消息可能需要添加 BREAKING CHANGE 页脚

步骤 3 — 生成 3 个选项

准确输出 3 个提交消息选项。每个选项单独一行，并放在代码块中。

风格规则（根据步骤 1b 检测到的仓库风格调整）：

如果仓库使用 Conventional Commits（在步骤 1b 中检测到）：

• 使用 type(scope): subject 格式——fix、feat、refactor、chore、docs、test、build
• 范围可选；如果更改的文件显示出明确范围，则添加范围
• 主题使用小写和祈使语气，≤72 个字符
• 如果检测到破坏性更改：添加空行 + BREAKING CHANGE: <what changed>

如果仓库使用 普通风格（或没有明确模式）：

• 主题行使用 小写
• 主题约 50 个字符（最多 72 个字符也可以）
• 不使用 Conventional Commits 前缀——使用 fix tokens not expiring，而不是 fix: resolve token expiry
• 使用祈使语气——使用“fix X”，而不是“fixed X”或“fixes X”

两种风格都适用：

• 略去明显的赘词——不要写“update code to fix the issue with the login”
• 正文可选——只有更改确实需要说明时，才添加空行和 1-2 行正文（每行 ≤72 个字符）

应避免的反模式：

• ❌ implement JWT token validation middleware with expiry checking
• ❌ refactor: extract authentication logic into separate service module
• ❌ fix: resolve issue with user authentication token expiration handling
• ✅ fix tokens not expiring
• ✅ move auth to its own file
• ✅ bump deps
• ✅ add dark mode toggle
• ✅ fix login redirect on mobile

输出格式

普通风格：

Option 1: fix tokens not expiring
Option 2: auth middleware wasn't checking expiry
Option 3: fix expired jwt tokens still passing through

Conventional Commits 风格：

Option 1: fix(auth): tokens not expiring on check
Option 2: fix(auth): jwt expiry not validated
Option 3: fix: expired tokens still passing auth middleware

带正文（有用时）：

Option 2: reorganize auth module

pulled jwt logic out, the file was getting too long

带破坏性更改页脚：

Option 1: refactor(api): rename user endpoints

BREAKING CHANGE: /users/:id renamed to /users/:userId

将最佳选项选为选项 1。