Commit Message Specification

When to Use

• 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

Step 1: Review Changes

git status
git diff --cached --stat   # Overview of staged changes
git diff --cached          # Detailed changes

git add

Step 2: Determine Type and Scope

feat(auth): add login interface

Step 3: Generate Commit Message

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

<body(optional)>

<footer(optional, such as BREAKING CHANGE)>

• 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.

Step 4: Output and Apply

git commit -m "<subject>" -m "<body>"

Cheat Sheet

Input and Output

• Input: Git staged changes (or changes described by the user);
• Output: Standardized commit message (may include body).

Examples

git add src/login.py tests/test_login.py

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(cart): fix incorrect calculation of cart discount amount

The discount was overcalculated by 1 cent after rounding. Changed to calculate first then round.

feat(api): remove v1 login interface

BREAKING CHANGE: v1 /login interface has been removed, please migrate to v2 /login.

Helper Script

git add -A
python scripts/commit_message_gen.py

Notes

• 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

• 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. 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.