Commit Messages That Don’t Suck

Good commit messages are the unsung heroes of a clean codebase. Learn how to write commits that help your team, your future self, and even your rubber duck.

Writing a commit message might seem like a small detail… until you have to read a cryptic fix things message six months later and wonder what past-you was thinking. A good commit is more than just version history — it’s a breadcrumb trail for your future self and teammates.

This guide will show you how to make your commit messages clear, consistent, and even a bit stylish 🕶️.

Why Commit Messages Matter

First of all, it’s very important to communicate a clear and understandable meaning of the changes we made. A well-written commit message helps teammates and future developers understand:

What was modified
Why it was changed
How it affects the project

Here’s why this is crucial:

✅ Improved Collaboration – Clear messages make it easier for team members to follow project progress and understand recent changes.
🐞 Easier Debugging – When investigating an issue, descriptive commit messages help identify which changes might have introduced a bug.
🧠 Better Documentation – The commit history serves as a timeline of the project’s evolution.
🔍 Efficient Code Reviews – Well-structured messages allow reviewers to quickly grasp the context of a change.

Commit Structure

A good commit message should follow a standard format:

<type>(<scope>): <short description>
[optional] Longer description explaining what changed and why.
[optional] References to related issues or PRs.

Example:

feat(login): add password input field
The login screen now includes a password input field to enhance security.
Fixes #123

Examples: Good vs Bad

✅ Good Commit Messages:

feat(login): add password input field
fix(cookie-policy): fixed broken links inside the cookie policy screen
refactor(api): optimized Google Places request for better performance

❌ Bad Commit Messages:

added things
fix var
stuff changes

Prefix Rules

chore
General maintenance tasks that don’t modify the code logic (e.g., updating dependencies, build scripts, etc.).
feat
A new feature or functionality.
fix
A bug fix.
style
Changes related to UI, design, or visual appearance (e.g., CSS updates, UI tweaks, animations).
loc
Changes related to localization or translations.
doc
Documentation updates or additions.
tests
Adding or updating tests.
refactor
Code restructuring without changing behavior (e.g., improving readability, optimizing performance).
ios
Changes specific to the iOS platform.
android
Changes specific to the Android platform.
conf
Changes related to configuration files or settings.
crc
Code review changes, addressing feedback or minor adjustments.

Nice to Have

🧩 Issue tracking
Reference issue numbers in the commit message (e.g., Fixes #123).
🧪 Atomic commits
Ensure each commit introduces only one logical change to keep the history clean.
✍️ Descriptive but concise messages
Keep the subject line under 72 characters while still being informative.
⌛ Use present tense and imperative mood
Instead of “Added new login flow”, write “Add new login flow”.

Final Thoughts

Next time you're tempted to type update, take a deep breath — and give your future self a gift. A good commit message might seem small, but when everyone on the team commits (pun intended) to writing them well, everything becomes smoother: debugging, reviewing, documenting… even onboarding new devs.

So go ahead, write that legendary feat(auth): add biometric login, Gitlog: now 30% sexier. 💅