The One Commit Message Trick That Saved My Sanity

Quick context (why you're writing this)

Here's the thing: I once spent three hours tracking down a regression that turned out to be a one‑line change buried in a commit that simply said “fix bug”. No clue what bug, why the change was needed, or what part of the system it touched. I ended up staring at a diff, guessing intent, and finally finding the answer in a Slack thread from two weeks prior. That moment made me realize how much time we waste when commit messages are an afterthought.

If you’ve ever stared at git blame and wondered “why did they do this?”, you know the feeling. The good news is there’s a single habit that flips the script: write your commit message as a short story of why the change exists, not just a list of what changed.

The Insight

The best practice I swear by is: start with a concise imperative summary (≤50 characters), leave a blank line, then explain the motivation, context, and any relevant references.

Why does this matter?

• Future you (or a teammate) can grasp the intent at a glance without digging through the diff.
• Tools like git bisect, release notes, and changelog generators rely on that first line to produce useful output.
• Code reviews become faster because reviewers see the “why” up front and can focus on correctness rather than guessing motive.

It’s not about being perfect; it’s about being helpful. A good commit message is a gift to your future self and to anyone who inherits the code.

How (with code)

The mistake we all make

fix bug

That’s it. No context, no reasoning. If you run git log --oneline you’ll see a sea of vague lines like “update stuff”, “refactor”, or “wip”. When you need to know why a particular line changed, you’re forced to open the commit, read the diff, and infer intent—often incorrectly.

A slightly better attempt

fix null pointer exception in user profile page

Now we know what broke, but we still don’t know why the exception happened or what the fix actually does. The reader still has to guess whether we checked for null, used a default value, or changed the calling code.

The meaningful version

fix: prevent NPE when user lacks avatar image

When a user profile is loaded, the avatar URL is fetched from
`userService.getAvatarUrl(userId)`. For newly registered users
this method returns `null`, which caused a NullPointerException
in the AvatarComponent’s `ngOnInit`.  

Instead of letting the exception bubble up, we now return a
placeholder URL (`/images/default-avatar.png`) when the service
returns `null`. This keeps the UI stable and avoids logging
spurious errors.  

References: #1423 (JIRA ticket), see also the design doc
`docs/avatar-handling.md`.

What changed?

1. Imperative, present‑tense summary (fix: prevent NPE when user lacks avatar image) – under 50 characters, starts with a verb, and tells the reader the effect of the change.
2. Blank line – separates the title from the body, which is the conventional format Git expects.
3. Body – explains the why (the scenario that triggered the bug), the how (what we actually did), and adds a reference to a ticket or doc for deeper context.

If you ever need to revert this commit, the message tells you exactly what behavior you’re losing and why it was added in the first place.

Why This Matters

I’ve seen teams cut their debugging time in half just by adopting this habit. When a bisect lands on a commit with a clear “why”, you can decide instantly whether the change is the root cause or a red herring. During code reviews, reviewers spend less time asking “what problem does this solve?” and more time evaluating the solution itself.

Even automated tooling benefits: many changelog generators (like conventional-changelog) parse the first line and the body to produce readable release notes. A vague commit like “fix bug” ends up as “fix bug” in the notes—useless for anyone scanning what’s new. A well‑crafted message turns that line into a meaningful entry that customers and support teams can actually understand.

The trade‑off? It takes a few extra seconds to write a decent message. But those seconds pay off instantly when you or a teammate needs to understand the code months later. Think of it as investing in a tiny piece of documentation that lives right where the change happens—no extra wiki page required.

Wrap‑up

Give it a try on your next pull request. Write the headline first, hit enter, then answer the question “why did I need to make this change?” in plain English. If you find yourself struggling to explain the why, maybe the change itself needs more thought.

Challenge: Look at your last five commits. Rewrite one of them using the format above and see how it feels to read back through the log. Does it make the story clearer? Drop a note in the comments—let’s learn from each other’s commit histories.

Happy committing!