Have you ever had the experience where you wrote some code a few months ago, and now you want to review the details of a specific modification. You open the Git commit history, only to see vague descriptions like “modified,” “made some changes,” or “fixed a bug”—and you have no idea what was actually changed? Or when collaborating with a team, if someone else’s commit records are messy, and you need to quickly find the changes for a specific feature, you end up flipping through pages without a clue? In such cases, a clear Git commit message becomes invaluable.

What is a commit message?¶

Every time you run git commit to submit your code, the descriptive text you write is the commit message. It serves as a “diary” of code changes, concisely telling others (and your future self) what was changed in this commit and why it was changed.

Why write a clear commit message?¶

You might think, “Just write a couple of lines, it’s fine.” But a clear commit message actually has many hidden benefits:

1. Rapid Recall: Save Your “Amnesiac” Self¶

Imagine you worked on a project six months ago and now need to optimize a feature. You open the commit history and see: “commit 1: modified code” and “commit 2: fixed a bug”—you can’t remember what was changed at all. But if the commit message is “fix: fixed the payment page amount calculation error,” you’ll immediately understand it’s a correction related to the payment feature, saving you a lot of time.

2. Team Collaboration: Smooth Communication¶

In a team, everyone’s commit records need to be shared. For example, if a frontend colleague modifies the login page style, the backend colleague needs to see which commit affected the API. A clear commit message helps them quickly locate the change. For instance, “feat(login): added mobile phone verification code login” directly tells everyone: this is a new feature for the login module.

3. Automation Tools: Let Tools “Understand” Your Code¶

Many tools rely on commit messages to work automatically:
- Generate Version Logs (CHANGELOG): Based on different commit types (e.g., fix, feat), automatically generate version update notes without manual summarization.
- Automatic Version Bumping: A standardized commit message allows tools to determine the version type (e.g., fix corresponds to a patch version, feat to a minor version) and automatically update the version number in package.json.

4. Quick Bug Identification: Detective-Like Bug Hunting¶

If a bug occurs in production and you need to use git bisect to quickly identify which commit caused it, a clear commit message helps narrow down the scope efficiently. For example, “fix(checkout): fixed the issue where the shopping cart checkout button could be clicked repeatedly” directly points to the problem type and module, much faster than a vague “modified the shopping cart.”

The Simplest Standard: At Least “Type + Description”¶

You don’t need to pursue a complex specification initially. Start with a simple habit: clearly state “what this commit does” and ideally include a “type” and “core content”.

Common Types (Stick to 2-3 basic ones):¶

• fix: Fix a bug (e.g., “fix: fixed the user registration failure issue”)
• feat: Add a new feature (e.g., “feat: added product search functionality”)
• docs: Update documentation (e.g., “docs: supplemented API interface documentation”)
• style: Formatting changes (e.g., “style: unified code indentation format”—does not affect logic)
• refactor: Code refactoring (e.g., “refactor: split repeated login logic into a function”)

Example:¶

# Basic version
git commit -m "fix: fixed the issue where the login button had no response"

# Advanced version (with scope, optional)
git commit -m "feat(home): added a homepage carousel component"

• (home) is the scope, indicating the change was made in the home module;
• fix/feat is the type, clarifying the nature of the change;
• The description that follows is concise and focuses on the core content—avoid being overly verbose.

A More Standardized Option: Conventional Commits Specification¶

If you want your commit messages to be more standardized, refer to the Conventional Commits specification. It has a stricter format, making it parsable by tools, and is ideal for collaborative projects.

Core Format:¶

<type>[optional scope]: <description>

[optional body]

[optional footer]

Common Types:¶

• feat: New feature (e.g., “feat: added the user personal center page”)
• fix: Bug fix (e.g., “fix(auth): fixed the functionality to resend verification codes after expiration”)
• docs: Documentation update (e.g., “docs: supplemented README.md installation steps”)
• chore: Routine task (e.g., “chore: updated dependency package versions”—does not affect code logic)

Example:¶

# With body and footer (optional, for advanced use)
git commit -m "feat(cart): added the ability to modify shopping cart item quantities

- Support +/- buttons to adjust quantities
- Synchronously update total price calculation

Fixes #123  # Links to an issue number, optional"

Beginner Tips for Practice¶

1. Start with “Type + Description”: Even if you only use fix/feat initially, gradually add scope and details later.
2. Write It 10 Seconds Before Committing: Spend 10 seconds before each commit to clarify the “core content of the change,” avoiding confusion when you revisit the code later.
3. Use Tools for Assistance: Recommended tools include cz-cli (interactive commit, automatically helps you select the type and write descriptions) or commitlint (checks if the format is compliant). Installing these can reduce errors.

Conclusion¶

A clear commit message is not a “burden” but a “shortcut” to improve code management efficiency. It helps you and your team members understand code changes faster and allows tools to automate versioning, logging, and other tedious tasks. From today onward, spend 5 seconds before each commit to think about “what I’m going to write.” With consistency, you’ll find your code repository becomes much more “readable”!