The Quest Begins (The "Why")
Honestly, I used to treat commit messages like an after‑thought. I’d hammer out a feature, stare at the terminal, and type something vague like fix bug or update files. It felt like checking a box, not leaving a trail. Then one rainy Tuesday I was tasked with tracking down a regression that had slipped into production three weeks prior. I opened the Git history, scrolled through a sea of fix, wip, and stuff commits, and felt like I was trying to read a map written in invisible ink. After two hours of bisecting, cherry‑picking, and muttering at my screen, I finally found the offending line buried in a commit that simply said refactor. The worst part? The author had no idea why they’d made that change, and neither did I. That moment was my “aha!”—I realized a commit message isn’t just etiquette; it’s the storybook that future developers (including my future self) will read when they need to understand why the code looks the way it does.
The Revelation (The Insight)
The best practice that changed everything for me is writing commit messages that answer the why behind the change, not just the *what*. Think of each commit as a mini‑chapter in a novel. If you only describe the plot points (added login button), you lose the motivation (to reduce friction for new users). When you explain the reason, you give reviewers context, you make debugging faster, and you turn your repository into a living documentation source.
Why does this matter? Because code is read far more often than it’s written. A clear why lets someone:
- Revert safely – they know what behavior they’re undoing.
- Cherry‑pick confidently – they understand side effects.
- Onboard newcomers – the history becomes a guided tour.
- Avoid repeat mistakes – the rationale prevents the same “quick fix” from being reapplied blindly.
In short, a good commit message transforms a cryptic log into a conversation across time.
Wielding the Power (Code & Examples)
Let’s look at a typical workflow and see how the message evolves.
Before: The Vague Whisper
git commit -m "fix bug"
What happened? We fixed a bug.
Why? Unknown.
Impact? A teammate later spends 30 minutes guessing whether the bug was UI‑related, API‑related, or a typo.
After: The Clear Chronicle
git commit -m "fix: prevent duplicate form submissions on slow networks
When the API latency exceeded 2 seconds, users could click the submit
button multiple times, creating duplicate orders. This change disables
the button after the first click and re‑enables it only after a successful
response or a timeout."
What happened? We disabled the submit button after the first click.
Why? To stop duplicate orders caused by high latency.
Impact? Anyone reading this later instantly knows the problem, the solution, and the edge case we considered.
Another Common Trap: The “WIP” Commit
git commit -m "wip: work on login flow"
This tells us nothing except that the author was in the middle of something. If the work gets abandoned or needs to be revisited, we’re left with a dead end.
Improved Version
git commit -m "feat: add email validation to login form
The previous implementation accepted any string, leading to accounts
with malformed email addresses that broke password‑reset emails.
Added a simple regex check and an inline error message that appears
when the field loses focus."
Now the commit tells the story: what we added, why it was needed, and how it works.
The Magic Trick: Imperative Mood & Length
A quick style note that makes messages readable: start with an imperative verb (fix, add, remove, refactor) and keep the subject line under 50 characters. If you need more detail, add a blank line followed by a body wrapped at 72 characters. This mirrors the conventional format many tools (like GitHub) expect and makes the log scan‑friendly.
git commit -m "refactor: extract password validation to a service
The validation logic was duplicated across the register and reset
pages, making future changes error‑prone. By moving it to a dedicated
service we ensure a single source of truth and simplify unit testing."
See how the subject line tells the what and the body explains the why? That’s the sweet spot.
Why This New Power Matters
When you start writing messages that explain the rationale, you’ll notice a few immediate wins:
- Code reviews become faster – reviewers can see the problem you’re solving without digging through the diff.
-
Regression hunts shrink – a
git bisectthat lands on a commit with a clear why often tells you instantly whether that change is the culprit. - Team knowledge spreads – new hires can read the commit history as a mini‑tutorial on why the system evolved the way it did.
- Your future self thanks you – six months later you’ll thank past‑you for saving you from a rabbit‑hole of guesswork.
I still remember the first time I used this practice on a stubborn bug. I wrote a commit that said, “fix: stop infinite scroll from triggering on empty state – the IntersectionObserver callback wasn’t checking for zero‑length lists”. When the same symptom popped up months later, I searched the log, found that message, and realized the fix was already there. It felt like discovering a hidden shortcut in a game—suddenly the level was beatable without grinding.
Your Turn: Embark on Your Own Quest
Here’s a challenge for you: the next time you make a commit, pause for a second and ask yourself, “If I were looking at this in six months, what would I need to know to understand why this change exists?” Write that answer in the body. Keep the subject short, imperative, and focused on the what. Watch how your Git log transforms from a cryptic scroll into a readable narrative.
Give it a try, share your favorite before/after commit messages in the comments, and let’s keep making our repositories tell stories worth reading. Happy committing! 🚀
