How to Write Meaningful Commit Messages: The Gandalf Approach

The Quest Begins (The “Why”)

I still remember the first time I opened a pull request and saw a wall of commits that read like a grocery list:

fix typo
update README
more changes
wip
done

I spent three hours trying to figure out why the build broke after a seemingly harmless “more changes” commit. The author had no idea what they’d touched, and I ended up scrolling through diffs like a detective in a noir film—except the clues were missing. That moment made me realize that a commit message isn’t just a formality; it’s the story of why we changed code, and when that story is vague, the whole team pays the price in wasted time and frustration.

The Revelation (The Insight)

The turning point came when I started treating each commit like a chapter in a book that future readers (including my future self) will actually want to read. The best practice that changed everything for me is simple: write the commit message as if you’re explaining the change to a teammate who has zero context.

That means answering two questions in the first line:

1. What did you change?
2. Why did you change it?

If you can answer those in ~50 characters, you’ve got a solid subject line. The body (if needed) then dives into the how and any side‑effects, but the subject line alone should let someone skim the history and instantly grasp the intent.

Why does this work? Because Git history is a timeline. When you can glance at it and see “Add JWT refresh token endpoint to support mobile clients” instead of “auth stuff”, you can quickly locate when a feature was introduced, spot regressions, or understand the rationale behind a design decision without digging through the code.

Wielding the Power (Code & Examples)

Let’s look at a real‑world scenario: fixing a bug where a user’s profile picture wasn’t uploading on Safari.

Before (the struggle)

fix bug

That’s it. No clue what bug, where it lived, or why it mattered. A teammate glancing at the log would have to open the diff, guess the file, and maybe still miss the Safari‑specific nuance.

After (the victory)

Fix Safari profile upload failure caused by missing FormData.append call

- In `src/components/AvatarUploader.js`, the `handleFileSelect` function
  was building a FormData object but never appending the selected file
  when the browser is Safari (detected via navigator.userAgent).
- Added `formData.append('file', file);` inside the Safari branch.
- Added a unit test covering the Safari code path.

Now the intent is crystal clear: what changed (the FormData line), why it was needed (Safari upload failed), and where to look (the component file). If a regression appears six months later, a developer can search “Safari profile upload” and land on this commit.

Common traps to avoid

Trap	What it looks like	Why it hurts
Vague verb	update, fix, wip	No indication of scope or motivation.
Too much detail in subject	Fixed the bug where the profile picture wouldn't upload on Safari because the FormData wasn't being appended in the handleFileSelect function	Hard to read in log views; pushes essential context into the body, which many tools truncate.
Missing why	Added FormData.append call	Tells you what but leaves you guessing the reason—was it a performance tweak? A security patch?

By steering clear of these pitfalls, each commit becomes a useful breadcrumb rather than a cryptic hieroglyph.

Why This New Power Matters

Adopting this habit transforms your workflow in three tangible ways:

1. Faster debugging – When a test fails, you can git bisect with confidence, knowing each step tells you exactly what changed and why.
2. Cleaner code reviews – Reviewers spend less time asking “what’s the purpose of this change?” and more time giving substantive feedback.
3. Better onboarding – New hires can read the commit history like a narrative, grasping the evolution of features without needing a senior engineer to walk them through every PR.

It feels like gaining a super‑power: the ability to speak across time through your commits. Suddenly, the repository isn’t just a dump of snapshots; it’s a living documentation of intent, decisions, and lessons learned.

A quick challenge

Next time you’re about to hit git commit, pause for ten seconds and ask yourself:

• If I were reading this line in a year, would I instantly know what was done and why?

If the answer is no, rewrite the subject line until it is. Give it a try on your next small tweet‑sized fix or refactor, and watch how the history starts to read like a well‑written story rather than a fragmented diary.

Happy committing, and may your logs always be clear! 🚀