On Writing Good Commit Messages: Why They Matter and How to Master Them

A developer's confession: How I learned to stop writing terrible commit messages and actually help my team

So I was plowing through The Odin Project when I was learning full stack development (amazing resource, btw), when I stumbled across something that kinda blew my mind. Not in a “quantum physics” way, but in that “how did I not know this before?!” way. It was all about writing decent commit messages.

Before that? Man, my commit history was ROUGH. Like, embarrassingly bad. I’d write things like “Added stuff” or “Fixed it” or my personal favorite: just the word “Add” over and over again. Past tense, present tense, whatever felt right in the moment. Zero consistency.

Then I had to work on my first group project. YIKES.

That’s when it hit me — these messages aren’t just little notes to myself. They’re like breadcrumbs for everyone who comes after me (including future-me who will 100% forget what I did 3 months ago). Go take a peek at your early commits right now. I’ll wait… Pretty messy, right? We’ve all been there!

So how do you write commit messages that don’t make your teammates want to scream? Let me break it down.

Why This Actually Matters (I Promise)

When you’re coding solo, it’s easy to think “who cares?” But trust me on these:

Team Sanity: Your team needs to understand what you did without diving into every line you changed. I once spent 2 hours trying to figure out what my teammate meant by “fixed stuff” only to discover he’d completely rewritten our auth flow. 😑

Debugging Hell: Ever had to track down when something broke? Good commit messages are like a map through the wilderness. Bad ones are… well, not.

The Tools Thing: GitHub, Jira and all those fancy CI pipelines can actually do cool automated stuff with well-written commits. I never knew this until my tech lead showed me!

The “Not Terrible” Commit Message Formula

I’ve boiled it down to two main parts:

1. The Headline (keep it short & sweet)
2. The Body (optional but super helpful)

For The Headline:

Use commands — Think like you’re ordering your code around: “Add feature” not “Added feature” or “Adding feature”

Like, imagine starting with “This commit will…” and go from there:

✅ Add login button to navbar
❌ Added login button to navbar

See the difference? Small but important!

Keep it SHORT — Under 50 characters. This is harder than it sounds!

No period at the end — Just a weird convention but people get annoyed if you add one.

Capitalization matters— Start with a capital letter because… aesthetics, I guess?

The Details (When You Need More Space):

Skip a line after your headline, then explain:
- WHY you made the change (not just what you did)
- Any weird decisions that need explaining
- References to issues or tickets

Here’s one I wrote last week that my senior dev actually complimented:
Add password reset functionality

Implements email-based password reset flow using SendGrid.
This addresses user feedback from last month’s survey where
12% of support tickets were about forgotten passwords.

Relates to: JIRA-420

Prefixes That Make You Look Like You Know What You’re Doing

Some teams use these little prefixes to categorize commits. I resisted at first (seemed like overkill) but now I’m a convert:

feat: when you add something cool
- fix: when you squash a bug
- docs: when you’re just updating documentation
- style: for formatting stuff, not actual code changes
- refactor: when you rewrite code but it still does the same thing
- perf: when you make things faster
- test: adding/fixing tests
- chore: boring maintenance stuff

Like this morning I pushed: fix: stop login form from erasing email on failed attempt

Way better than “Fixed login bug” right?

Pro Tips From My Hard-Learned Mistakes

One change, one commit— I used to bundle 5 different things into one commit. Don’t be like me.

Think before you commit — Take 30 seconds to actually think about what you did.

Review your own messages— I sometimes rewrite mine 2–3 times before pushing.

Be consistent-ish— Find a style that works for you and mostly stick to it.

What The Real Pros Do

I looked up how Linus Torvalds (you know, the Linux/Git guy) writes commits, and while his messages sometimes get pretty intense, his basic rules are:

1. Short subject line that makes sense
2. No period at the end of subjects
3. Explain the WHY not just the what

Checkout commit messages of linux kernel or git repository or anything by Tim Pope. You can read the git logs in their github repository.

There’s this great article by Chris Beams called “How to Write a Git Commit Message” that dives deeper if you’re interested!

Final Thoughts

Look, I’m not perfect at this yet. Sometimes at 2 AM I still write “fix stuff” when I’m desperate to go to bed. But my commit history is WAY less embarrassing now.

Remember — you’re not just talking to Git, you’re leaving notes for other humans. And sometimes that human is you, six months later, wondering what the heck you were thinking.

So take the extra 10 seconds. Your team (and future you) will thank you.

P.S. — Check these out if you want to go deeper:
- Conventional Commits (google it — there’s a whole spec)
- That Chris Beams article I mentioned

What’s your worst commit message ever? Mine was literally just “update” at 3 AM once. Not my proudest moment! 😂