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 add
,或询问是否查看工作区改动。
Execute and analyze:
bash
git status
git diff --cached --stat   # Overview of staged changes
git diff --cached          # Detailed changes
If the staging area is empty, prompt the user to run
git add
first, or ask if they want to review changes in the working directory.

第 2 步:确定类型与范围

Step 2: Determine Type and Scope

类型(必选):
类型含义
feat新功能
fix修复 Bug
docs文档
style格式(不影响逻辑)
refactor重构(不改变行为)
perf性能优化
test测试
build构建/依赖
chore杂项
revert回滚
范围(可选):模块名,如
feat(auth): 增加登录接口
。
Type (required):
TypeMeaning
featNew feature
fixBug fix
docsDocumentation
styleFormatting (no impact on logic)
refactorRefactoring (no change in behavior)
perfPerformance optimization
testTesting
buildBuild/dependencies
choreChores
revertRevert
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
    BREAKING CHANGE:
    explanation.

第 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.py
Generated:
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 interface
Fix 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.py
The 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
    git commit
    without confirmation (show it to the user first);
  • 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

  1. 触发:"写个 commit message";
  2. 检查:格式为
    <type>: <subject>
    ,subject ≤ 72 字符且动词开头;
  3. 抽查:对照
    git diff
    ,确认描述与改动一致。
  1. Trigger: "write a commit message";
  2. Check: Format is
    <type>: <subject>
    , subject ≤ 72 characters and starts with a verb;
  3. Spot check: Compare with
    git diff
    to ensure description matches changes.