In daily development, we often use Git for version control. Writing a clear commit message is actually very important every time we commit code. However, many beginners might think, “Just a few words will do,” but in reality, non-standard commit messages can cause a lot of trouble for team collaboration.

Why is a standardized commit message needed?¶

Imagine:
- If there are 10 people on the team and everyone writes very casual commit messages (e.g., “Changed something,” “Fixed it”), after two weeks, you want to find out who submitted a bug but discover all commits are the same—no trace at all.
- If you need to explain the project’s update history to others, like “This is a major version upgrade,” but the commit messages are all scattered changes, it’s impossible to make sense of the logic.

A standardized commit message is like writing a “manual” for each code commit, allowing team members to quickly understand what was done in the commit, facilitating collaboration, issue tracking, and version management.

What does a standardized commit message look like?¶

The most popular specification is Conventional Commits, which is based on the commit specifications of the Angular project and has become an industry standard. Simply put, a standardized commit message can be divided into several parts:

<type>[optional scope]: <short description>

[optional body (detailed explanation)]

[optional footer (related issues or breaking changes)]

1. Type: Indicates the nature of the commit¶

The type is required and tells others whether the commit is a “new feature,” “bug fix,” or “documentation update,” etc. Common types include:
- feat: New feature (e.g., adding a button, new API).
- fix: Bug fix (e.g., fixing a page display error).
- docs: Documentation-related (e.g., updating README or comments).
- style: Formatting adjustments (no impact on code logic, e.g., changing indentation, adding spaces).
- refactor: Code refactoring (neither new feature nor bug fix, e.g., optimizing function structure).
- test: Adding or modifying test code.
- chore: Trivial tasks (e.g., updating dependencies, modifying build scripts).

Example:
feat(user module): Add login verification code feature

2. Scope: Optional, limits the scope of the commit¶

The scope is optional and specifies the code module or functional area affected by the commit. For example, if the project has “user module,” “cart module,” “payment module,” adding a scope helps pinpoint changes more accurately.

Example:
fix(cart): Resolve error when product quantity is 0 during checkout

3. Description: Briefly describes the commit content¶

The description is required and should be concise, explaining what the commit does. Usually, use the imperative mood, such as “add,” “fix,” “optimize,” etc.

Example:
feat(user module): Add login verification code feature
(The description part directly states “Add login verification code feature”)

4. Body: Detailed explanation (optional)¶

If the description is insufficient, the body can elaborate on the purpose, reason, or implementation of the commit. For example, why the change was made and what problem it solves.

Example:

feat(user module): Add login verification code feature

The previous login logic only used passwords, making it vulnerable to brute-force attacks. Now we've added two verification methods: SMS and email codes, improving security.

5. Footer: Related issues or breaking changes (optional)¶

The footer can be used to link to the project’s issues (e.g., which problem was fixed) or indicate breaking changes.
- Breaking Changes: If the commit affects existing code logic (e.g., changes to API parameters), it must be noted in the footer.
- Related Issues: For example, Closes #123 means this commit resolves issue #123.

Example:

fix(user module): Fix infinite loop caused by failed login

When users entered incorrect passwords continuously, the system didn't limit the number of attempts, causing an infinite loop. Now we've added a logic to lock the account after 5 failed attempts.

Closes #456

Standardized commit message templates and examples¶

Template format:¶

<type>[optional scope]: <short description>

[optional body]

[optional footer]

Example 1: New feature (feat)¶

feat(payment): Add WeChat Pay functionality

Supports users to pay via WeChat QR code, expanding payment channels.

Closes #78

Example 2: Bug fix (fix)¶

fix(cart): Resolve duplicate calculation of items during checkout

Previously, when users added the same product multiple times, the settlement amount would be cumulatively added. Now the quantity calculation logic is fixed to ensure each product is counted only once.

Fixes #123

Example 3: Breaking Change¶

feat(api): Add new user query API

A new `/api/user/list` interface is added, but the old interface `/api/users` is deprecated. Callers must upgrade to the new interface.

BREAKING CHANGE: The old interface `/api/users` is deprecated. The new interface's return format has been adjusted to...

How to develop the habit of writing standardized commit messages?¶

1. Remember common types¶

• feat (new feature), fix (bug fix), docs (documentation), chore (trivial tasks) are the most commonly used.

2. Use tools for assistance¶

• commitizen: Interactive command-line tool that guides you through selecting type, scope, and description, avoiding manual formatting errors.
• Installation: npm install -g commitizen
• Usage: Replace git commit with git cz and follow the prompts.
• commitlint + husky: Automatically checks if commit messages meet the standard and blocks non-compliant commits before they are submitted.

Benefits of standardization¶

• More efficient team collaboration: Members can quickly understand the commit content without checking the code.
• Automatic version log generation: Tools like standard-version can automatically generate ChangeLogs based on commit messages, directly corresponding to version update content.
• Clearer issue tracking: Directly link commits to issues via Closes #123, ensuring one-to-one correspondence between commits and problems.
• Early warning of breaking changes: Breaking changes are explicitly marked to avoid affecting other modules.

Summary¶

While standardized commit messages are not mandatory, developing this habit significantly improves team collaboration efficiency. Remember the core principle: Type + Description + Necessary Details to clearly state “what was changed and why.” It may require conscious practice at first, but once mastered, the benefits far outweigh the time invested.

Next time you commit code, try using the standardized format!