←All posts

The Art of Writing Good Commit Messages

 — #Git#Best Practices#Developer Habits#Productivity

I used to treat Git commits like save points in a video game.

My git log looked something like this:

  • fixed bug
  • update
  • WIP
  • finally works
  • asdfghjkl

Then, I joined a team where I had to read other people’s code to figure out why a system broke at 2 AM. That’s when I realized: commit messages aren’t for you today. They’re for you (and your team) in 6 months.

Why Commit Messages Matter

Code tells you how something is done. A good commit message tells you why it was done.

When you’re tracking down a bug using git blame, seeing a commit message that says update styles is useless. Seeing fix: align header button to match new design spec (issue #42) gives you context, intent, and a breadcrumb trail.

A Simple Framework for Better Commits

You don't need a heavy, bureaucratic process. Just follow the Conventional Commits format. It takes zero extra time once you're used to it, and it makes scanning logs a breeze.

1. The Prefix (The "What")

Start every commit with a type. This forces you to categorize what you actually did.

  • feat: (New feature)
  • fix: (Bug fix)
  • docs: (Documentation changes)
  • style: (Formatting, missing semi-colons, etc.)
  • refactor: (Code change that neither fixes a bug nor adds a feature)
  • test: (Adding missing tests)
  • chore: (Updating build tasks, package manager configs, etc.)

2. The Subject (The "Why")

Write a concise, imperative sentence. Imagine you are completing the sentence: "If applied, this commit will..."

  • ❌ added login button (Past tense)
  • ❌ login button (Not a sentence)
  • ✅ feat: add login button to navigation header (Imperative, clear)

3. The Body (The "Context") - Optional but powerful

If the change is complex, leave a blank line after the subject and explain why this change was made. What was the problem? What approach did you take? What edge cases did you consider?

fix: resolve race condition in user authentication
 
The auth token was occasionally being cleared before the redirect 
completed on slow connections. Moved the token clearance to the 
unmount lifecycle of the login component.
 
Fixes #123

The Atomic Commit Rule

The secret to good commit messages is writing good commits. Make atomic commits.

A commit should do one thing. If you find yourself writing feat: add login and fix CSS on pricing page and update README, you should have made three commits.

The Payoff

Writing good commit messages feels like eating your vegetables at first. It takes a little discipline. But the first time you use git log to instantly understand why a weird architectural decision was made two years ago, you'll never go back to WIP again.