git-commit

Git Commit

编写简洁、原子化且能清楚表达意图的提交。

何时使用此技能

符合以下任一条件时启用：

• 用户要求“提交”“创建提交”“暂存更改”或“编写提交消息”
• 用户说“提交我的更改”或“提交这个”
• 一个逻辑工作单元已完成，可以合并
• 用户询问 git add、git commit 或 git amend

决策树

What does the user need?

Stage + commit changes?
  → Check what changed: git status + git diff --staged
  → Group related changes (atomic commit rule below)
  → Write message in conventional format
  → If hook fails: fix root cause, re-stage, new commit

Amend the last commit?
  → ONLY if NOT yet pushed to remote
  → OK for: missing file, minor message fix, small oversight
  → New commit instead: substantial change, already pushed

Write a commit message only?
  → Follow conventional format below
  → Lead with "why", not "what"

Hook failure?
  → Read the full hook output
  → Fix the root cause — never use --no-verify

Conventional Commits 格式

<type>(<scope>): <subject>

<body>      ← optional; explain *why*, not *what*
<footer>    ← optional; breaking changes, refs

类型

类型	适用情况
feat	新功能或新能力
fix	修复 Bug
refactor	重构代码，不改变行为
docs	仅修改文档
test	添加或修复测试
chore	构建、工具或依赖更新
perf	性能改进
ci	CI/CD 工作流变更

规则

• 主题：≤ 72 个字符，使用祈使语气（用 “add”，不要用 “added”），末尾不加句号
• 正文：每行不超过 72 个字符；说明动机，而非实现细节
• 破坏性变更：使用 BREAKING CHANGE: 页脚，或在类型后加 !（如 feat!:）

原子化提交

一次提交 = 一个逻辑变更。审阅者无需查看其他提交就应能理解该提交。

一起提交： 单个功能或修复涉及的所有文件；与所覆盖代码对应的测试。

分开提交： 将重构与行为变更分开；将无关修复分开；将未完成的工作分开。

切勿提交 “WIP” 或 “misc fixes”——最终定稿前应合并或拆分提交。

暂存检查清单

运行 git add 前，请确认：

• 不包含机密、API 密钥或凭据
• 不包含调试代码或临时变通方案（console.log、TODO: remove）
• 更改彼此相关（属于一个逻辑单元）
• 遵循 .gitignore——除非有意保留，否则不包含构建产物或生成文件

示例

功能

feat(auth): add OAuth2 login flow

Replaces username/password form. Supports Google and GitHub as providers.
Token refresh is handled automatically by the auth middleware.

Bug 修复

fix(publish): handle missing platform binary gracefully

Previously threw unhandled error when the platform package was absent.
Now logs a clear message and exits with code 1.

破坏性变更

feat!: change publish config to support multiple binaries

BREAKING CHANGE: `binary` field renamed to `binaries` array.
Migrate: `binary: 'my-cli'` → `binaries: [{ name: 'my-cli', ... }]`

日常维护

chore(deps): upgrade pnpm to 10.6.2

提交前钩子失败

1. 阅读完整的钩子输出——其中会明确指出失败原因
2. 修复根本问题（lint、类型错误、格式问题）
3. 重新暂存已修复的文件
4. 创建一个新提交——不要 amend 失败的提交
5. 除非用户明确要求，否则绝不要使用 --no-verify

设置与激活

npx skills add -g onsager-ai/dev-skills --skill git-commit -a claude-code -y

当用户说“提交”“暂存”“git add”或“提交消息”时自动启用。