Version control isn't just a backup system; it is a communication tool. A repository's history tells the story of how software was built, why decisions were made and who made them. Clear commits are one of the cheapest ways to make a codebase easier to maintain and a team easier to work with.

Why good commits matter

When a bug reaches production, developers reach for git log, git blame and git bisect to find where it came from. If the history is full of messages like "fix", "wip" and "update stuff", that search turns into reading every diff. Good messages also make code review faster, make release notes easy to write, and help future you remember why something is the way it is.

Use the imperative mood

A commit subject should complete the sentence "If applied, this commit will…". For example: "Add password reset endpoint" or "Fix memory leak in WebSocket handler". This matches the messages Git itself generates ("Merge branch…", "Revert…") and keeps the log consistent.

Structure: subject, blank line, body

Keep the subject to about 50 characters, start with a capital letter and leave off the trailing period.
Leave a blank line after the subject. Many tools rely on it.
Use the body to explain what changed and why. The diff already shows how.
Wrap the body at around 72 characters and reference issues ("Fixes #123") where relevant.

Fix duplicate charges on payment retry

Retries after a gateway timeout created a second charge because the
idempotency key was regenerated on each attempt. Reuse the key from
the original request instead.

Fixes #482

Make commits atomic

Each commit should contain one logical change that leaves the project working. Don't mix a refactor, a bug fix and a formatting change in one commit. Use git add -p to stage parts of files, and squash or reorder "fix typo" commits before merging.

Consider Conventional Commits

Many projects use the Conventional Commits format, with a type prefix like feat:, fix:, docs: or refactor:. It makes the history scannable and lets tools generate changelogs and version numbers automatically. Follow whatever convention the project already uses.

Good and bad examples

❌ fixed stuff → ✅ Fix crash when profile has no repositories
❌ WIP → ✅ Add rate limiting to public API endpoints
❌ Updated the code to use the new function that was added → ✅ Use shared date formatter in reports

Clean commits make you easier to collaborate with, which is also what open-source maintainers and hiring managers look for. Read more about how open source helps your career.

Writing Clean Commits: A Guide to Better Developer Collaboration