A well-written Git commit message is essential for maintaining a clean and understandable project history. It not only helps others understand why a change was made but also improves collaboration, debugging, and version control.
This guide will walk you through best practices for writing professional Git commit messages, including structure, tone, and formatting tips.
Why Commit Message Quality Matters
Poor commit messages lead to:
- Difficulty understanding code history
- Harder debugging and code reviews
- Inefficient team communication
Good commit messages:
- Document the what and why of changes
- Help onboard new developers
- Serve as a changelog
- Improve collaboration across teams
Standard Structure of a Commit Message
A professional Git commit message generally follows this structure:
<type>(<scope>): <subject>
<body> (optional)
<footer> (optional)
1. Type
Describes the kind of change. Common types include:
| Type | Meaning |
|---|---|
| feat | New feature |
| fix | Bug fix |
| docs | Documentation change |
| style | Code formatting, missing semi colons, etc. |
| refactor | Code change that neither fixes a bug nor adds a feature |
| perf | Performance improvement |
| test | Adding or modifying tests |
| chore | Changes to the build process or auxiliary tools |
2. Scope
Specifies the module, feature, or file affected. This is optional but helpful in large codebases.
Example: feat(auth): indicates a new feature in the authentication module.
3. Subject
A brief, imperative summary of the change. It should be:
- Written in lowercase
- No punctuation at the end
- In the imperative mood (e.g., “add”, “fix”, “refactor”)
Bad:added new login feature.
Good:add login feature to support SSO
Writing the Commit Body (Optional but Recommended)
The body should answer:
- What was done?
- Why was it done?
- How was it done (if not obvious)?
Tips:
- Wrap lines at 72 characters
- Use bullet points or paragraphs for clarity
- Use the imperative tone consistently
Example:
feat(auth): add two-factor authentication
Implemented TOTP-based 2FA using the Google Authenticator standard.
Users can now link their account to an authenticator app and are
required to enter a 6-digit code during login after password verification.
Using Footers
Footers are used for:
- Breaking changes:
BREAKING CHANGE: ... - Linking issues:
Closes #123,Fixes bug #456
Example:
BREAKING CHANGE: removed legacy API endpoint /v1/user/login
Closes #112
Real-World Examples
fix(api): handle timeout error in payment gateway response<br><br>Added a 10-second timeout fallback for slow responses from Razorpay.<br>Improves UX during high latency situations.<br><br>Fixes #204<br>refactor(order): extract billing logic to service layer
Improves separation of concerns and makes the billing logic reusable
across different modules.
chore(deps): update lodash from 4.17.15 to 4.17.21
Tools to Enforce Good Commit Messages
- Husky + Commitlint: Enforce commit message conventions
- Conventional Commits: A standard for writing commit messages used in many CI/CD pipelines
- Semantic Release: Automates versioning and changelog generation using structured commits
Summary
| Rule | Description |
|---|---|
| Use the imperative mood | “Add” not “Added” or “Adds” |
| Limit the subject line to 50 chars | Keep it concise |
| Use a blank line before body | Follow standard formatting |
| Wrap the body at 72 chars | Improve readability |
| Include the what, why, how | Especially in multi-line commits |
| Use types consistently | Helps with automation and release pipelines |
Final Thoughts
Writing professional commit messages may seem tedious at first, but it pays off in long-term maintainability and team productivity. It’s a habit that distinguishes junior developers from seasoned professionals.
Make your commit messages meaningful — your future self (and your team) will thank you.
