If you’ve ever looked at your Git history and wondered “what was I thinking?”, you’re not alone. I used to write commits like “fix bug” or “update stuff”. Fast forward a few months, and I had no idea what those commits actually did 😅

This is what I learned about writing better commit messages. It’s not a strict rulebook, just practical tips that made my life easier.

Why Bother?

Good commit messages help you:

• Understand what changed and why
• Debug faster when something breaks
• Make code reviews smoother
• Onboard new team members easier

Think of commits as leaving notes for your future self.

The Basic Format

<type>: <what you did>

That’s it. Simple, right?

Types You’ll Actually Use

Good vs Bad Examples

Bad:

fix bug
update code
changes
stuff

Good:

fix: resolve login timeout after 30 seconds
feat: add password reset via email
docs: update installation steps for Windows
refactor: simplify user validation logic

Simple Rules

1. Start with a type

feat: add dark mode toggle
fix: prevent duplicate form submissions

2. Be specific

❌ fix user thing
✅ fix: prevent users from submitting empty forms

3. Use present tense

✅ add feature
❌ added feature

4. Keep it short Try to stay under 50 characters for the main message.

5. One change per commit Don’t mix unrelated changes in one commit.

When to Add More Details

For complex changes, add a blank line then explain:

feat: add Redis caching for sessions

Old implementation stored sessions in database causing
slow response times. Redis cache reduces load time by ~200ms.

Closes #123

But honestly? Most commits don’t need this. A clear one-liner is usually enough.

Optional: Scope

You can add scope to show what part of your app changed:

feat(auth): add Google login
fix(payment): resolve checkout crash
docs(readme): add quick start guide

Use it if it helps, skip it if it doesn’t.

Linking Issues

If you use GitHub issues:

fix: resolve payment processing error

Fixes #123

GitHub will automatically close issue #123 when this merges.

Common Mistakes

Too vague:

❌ fix stuff
❌ update

Too long:

❌ feat: add a new feature that allows users to do X and Y and also fixes Z

Better to split into multiple commits.

No type:

❌ added login page
✅ feat: add login page

Real Examples

Here are commits I actually write:

feat: add user profile page
fix: resolve null error in checkout
docs: update API examples
refactor: extract validation to helper function
chore: update dependencies
test: add tests for login flow
style: format code with prettier

Tools That Help

If you want to get fancy:

• Commitizen - Interactive tool to write commits
• Commitlint - Validates your commit messages
• Husky - Prevents bad commits from being pushed

But start simple. Just focus on clear, descriptive messages first.

Team Consistency

The most important thing? Be consistent with your team. If they write commits differently, follow their style. Create a simple CONTRIBUTING.md file documenting what your team prefers.

Bottom Line

Writing good commits isn’t hard:

1. Add a type (feat, fix, etc.)
2. Describe what you did clearly
3. Keep it short and simple
4. Be consistent

That’s it. Your future self will thank you when debugging at 2 AM 🙏

References

• Conventional Commits
• How to Write a Git Commit Message