commit-message-writer
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinese提交信息规范
Commit Message Specification
何时使用
When to Use
- 用户说"写个 commit message""帮我提交";
- 提交信息不规范(整段废话、不写类型、一句"update");
- 需要为改动生成规范且可检索的提交信息。
- When the user says "write a commit message" or "help me commit";
- When commit messages are non-standard (long rambling text, no type specified, just "update");
- When you need to generate standardized and searchable commit messages for changes.
使用步骤
Usage Steps
第 1 步:查看改动
Step 1: Review Changes
执行并分析:
bash
git status
git diff --cached --stat # 暂存区的改动概况
git diff --cached # 具体改动若暂存区为空,提示用户先 ,或询问是否查看工作区改动。
git addExecute and analyze:
bash
git status
git diff --cached --stat # Overview of staged changes
git diff --cached # Detailed changesIf the staging area is empty, prompt the user to run first, or ask if they want to review changes in the working directory.
git add第 2 步:确定类型与范围
Step 2: Determine Type and Scope
类型(必选):
| 类型 | 含义 |
|---|---|
| feat | 新功能 |
| fix | 修复 Bug |
| docs | 文档 |
| style | 格式(不影响逻辑) |
| refactor | 重构(不改变行为) |
| perf | 性能优化 |
| test | 测试 |
| build | 构建/依赖 |
| chore | 杂项 |
| revert | 回滚 |
范围(可选):模块名,如 。
feat(auth): 增加登录接口Type (required):
| Type | Meaning |
|---|---|
| feat | New feature |
| fix | Bug fix |
| docs | Documentation |
| style | Formatting (no impact on logic) |
| refactor | Refactoring (no change in behavior) |
| perf | Performance optimization |
| test | Testing |
| build | Build/dependencies |
| chore | Chores |
| revert | Revert |
Scope (optional): Module name, e.g., .
feat(auth): add login interface第 3 步:生成提交信息
Step 3: Generate Commit Message
格式:
text
<type>(<scope>): <subject>
<body(可选)>
<footer(可选,如 BREAKING CHANGE)>规则:
- subject 一句话概括,≤ 72 字符;
- subject 用祈使句:动词开头(增加、修复、重构);
- 中文描述为主,类型用英文约定词;
- 一个 commit 只做一件事;
- 破坏性变更必须写 说明。
BREAKING CHANGE:
Format:
text
<type>(<scope>): <subject>
<body(optional)>
<footer(optional, such as BREAKING CHANGE)>Rules:
- Subject is a one-sentence summary, ≤ 72 characters;
- Subject uses imperative mood: starts with a verb (add, fix, refactor);
- Chinese descriptions are preferred, types use agreed English terms;
- One commit should only do one thing;
- Breaking changes must include explanation.
BREAKING CHANGE:
第 4 步:输出并应用
Step 4: Output and Apply
输出完整提交信息供用户确认,确认后执行:
bash
git commit -m "<subject>" -m "<body>"Output the complete commit message for user confirmation, then execute the following after confirmation:
bash
git commit -m "<subject>" -m "<body>"速查表
Cheat Sheet
详细的类型列表、写法对比和模板见 references/CHEATSHEET.md。
For detailed type lists, writing comparisons, and templates, see references/CHEATSHEET.md.
输入与输出
Input and Output
- 输入:git 暂存区改动(或用户描述的改动);
- 输出:规范化的提交信息(可含正文)。
- Input: Git staged changes (or changes described by the user);
- Output: Standardized commit message (may include body).
示例
Examples
bash
git add src/login.py tests/test_login.py生成:
text
feat(auth): 增加用户名密码登录接口
- 使用 bcrypt 校验密码
- 登录成功返回 JWT,失败返回 401
- 补充登录接口单元测试修复示例:
text
fix(cart): 修复购物车满减金额计算错误
满减在四舍五入后多算了 1 分钱。
改为先计算再取整。破坏性变更示例:
text
feat(api): 移除 v1 登录接口
BREAKING CHANGE: v1 /login 接口移除,请迁移到 v2 /login。bash
git add src/login.py tests/test_login.pyGenerated:
text
feat(auth): add username-password login interface
- Use bcrypt to verify passwords
- Return JWT on successful login, 401 on failure
- Add unit tests for login interfaceFix example:
text
fix(cart): fix incorrect calculation of cart discount amount
The discount was overcalculated by 1 cent after rounding. Changed to calculate first then round.Breaking change example:
text
feat(api): remove v1 login interface
BREAKING CHANGE: v1 /login interface has been removed, please migrate to v2 /login.辅助脚本
Helper Script
scripts/commit_message_gen.py 根据暂存区改动生成提交信息草稿(推断类型和范围),不执行 commit:
bash
git add -A
python scripts/commit_message_gen.py生成的草稿需要人工完善 subject。
scripts/commit_message_gen.py generates a draft commit message based on staged changes (infers type and scope) without executing commit:
bash
git add -A
python scripts/commit_message_gen.pyThe generated draft requires manual refinement of the subject.
注意事项
Notes
- 不要用"update""修复了一些东西"这类无信息提交;
- 如果一次改动混杂多个类型,提示用户拆分成多个 commit;
- 未确认前不直接执行 (先给用户看);
git commit - 若仓库已有约定(如必须带 issue 号),遵循仓库约定并加入 footer。
- Do not use non-informative commits like "update" or "fixed some things";
- If a single change involves multiple types, prompt the user to split into multiple commits;
- Do not directly execute without confirmation (show it to the user first);
git commit - If the repository has existing conventions (e.g., must include issue number), follow them and add to the footer.
不适用场景
Unapplicable Scenarios
- 用户要的是提交策略建议(用 git-workflow);
- 改动尚未发生、纯设想场景;
- 用户明确指定了要写的内容。
- When the user needs commit strategy suggestions (use git-workflow);
- When changes have not occurred yet, purely hypothetical scenarios;
- When the user explicitly specifies the content to write.
验证方式
Verification Method
- 触发:"写个 commit message";
- 检查:格式为 ,subject ≤ 72 字符且动词开头;
<type>: <subject> - 抽查:对照 ,确认描述与改动一致。
git diff
- Trigger: "write a commit message";
- Check: Format is , subject ≤ 72 characters and starts with a verb;
<type>: <subject> - Spot check: Compare with to ensure description matches changes.
git diff