Git Commit Message Guidelines for Production
A well-written commit message is just as important as writing clean code. It helps your team understand what changed, why it changed, and makes debugging, code reviews, and release management significantly easier.
Commit Message Format
Follow this structure for every commit:
<type>(<scope>): <short summary>
<optional body>
<optional footer>
Example:
feat(auth): add Google OAuth login
Implemented Google OAuth authentication using Passport.js.
Added automatic account linking for existing users.
Closes #123
Subject Line Rules
The subject (first line) should follow these rules:
- Maximum 50 characters (recommended)
- Start with a lowercase commit type
- Use the imperative mood
- Do not end with a period (
.) - Be specific
- Describe what the commit does, not what you did
✅ Good
feat(auth): add password reset flow
fix(api): validate email before saving
docs: update Docker deployment guide
❌ Bad
Fixed bug
changes
Update
working
Body Rules
The body is optional but highly recommended for medium or large changes.
Explain:
- Why the change was needed
- What was changed
- Any side effects
- Any migration steps
Wrap lines around 72 characters.
Example:
fix(cache): prevent duplicate cache writes
The cache layer was writing duplicate entries whenever
multiple requests hit the endpoint simultaneously.
Added a distributed lock before cache writes to ensure
only one request populates the cache.
Footer Rules
Use the footer for:
- Issue references
- Breaking changes
- Pull requests
- Security notes
Example
Closes #42
Fixes #18
BREAKING CHANGE: API now requires authentication
Commit Types
feat
A new feature.
feat(auth): add GitHub login
fix
Bug fixes.
fix(api): prevent duplicate user creation
docs
Documentation only.
docs: update installation guide
style
Formatting changes only.
No logic changes.
style: format code with Prettier
refactor
Code improvements without changing behavior.
refactor(database): simplify query builder
perf
Performance improvements.
perf(api): reduce database queries
test
Adding or updating tests.
test(auth): add login integration tests
build
Changes affecting build tools or dependencies.
build: upgrade Node.js to v24
ci
Changes to CI/CD pipelines.
ci: add Docker image publishing
chore
Maintenance tasks.
chore: remove unused dependencies
revert
Revert a previous commit.
revert: revert OAuth implementation
security
Security-related fixes.
security(auth): sanitize JWT payload
Scope
The scope tells which part of the project changed.
Examples:
auth
api
database
docker
ui
payment
email
admin
config
ci
Example:
feat(payment): add Stripe webhook
Good Examples
Small feature
feat(user): add profile picture upload
Bug fix
fix(auth): prevent expired token reuse
Documentation
docs: add environment setup guide
Docker
build(docker): reduce image size
CI
ci(github): deploy Docker image after merge
Refactor
refactor(api): split validation logic
Performance
perf(database): add index to users table
Security
security(api): validate JWT issuer
Large Commit Example
feat(payment): integrate Stripe subscriptions
Added subscription creation and cancellation endpoints.
Implemented Stripe webhook verification.
Stored subscription status in the database.
Added retry logic for failed webhook events.
Closes #245
What NOT to Write
Avoid messages like:
update
changes
working
bug fixed
done
final
temp
misc
test
These provide no useful information.
Production Commit Checklist
Before committing, verify:
- Subject is under 50 characters
- Uses the correct commit type
- Includes a scope when appropriate
- Uses imperative mood
- No period at the end of the subject
- Explains what the change does
- Body explains why for non-trivial changes
- References related issues if applicable
Recommended Commit Workflow
1. Make one logical change
2. Review the diff
3. Write a meaningful commit message
4. Commit
5. Push
6. Open a Pull Request
Conventional Commit Cheat Sheet
| Type | Purpose |
|---|---|
| feat | New feature |
| fix | Bug fix |
| docs | Documentation |
| style | Formatting only |
| refactor | Code restructuring without behavior changes |
| perf | Performance improvement |
| test | Tests |
| build | Build system or dependencies |
| ci | CI/CD changes |
| chore | Maintenance tasks |
| revert | Revert previous commit |
| security | Security improvements |
Final Example
feat(notification): add email queue support
Implemented asynchronous email delivery using RabbitMQ.
Added retry handling for failed jobs.
Improved delivery reliability during high traffic.
Closes #321
This style follows the Conventional Commits specification and is widely used in production environments. It improves collaboration, enables automated changelog generation, semantic versioning, and makes project history easier to understand.
