Good commit messages make history searchable and reviews easier. A short, practical guide to the subject line, the body, and a few conventions worth adopting.
Open the history of a project and you will see messages like “fix”, “update stuff” and “wip”. They tell you nothing. Months later, when something breaks and you ask “why was this changed?”, a good message answers in seconds. A bad one leaves you reading the code from scratch.
The shape of a good message
A commit message has a short subject line, a blank line, and an optional body. The subject says what changed. The body explains why.
Fix crash when exporting an empty report
The export function assumed at least one row and read rows[0].
Return an empty file with headers instead, and add a test.
Fixes #214Five habits that help
- Use the imperative mood. Write “Add retry logic”, not “Added retry logic”. A good test: the subject should complete the sentence “If applied, this commit will...”.
- Keep the subject short. Around 50 characters shows fully in most tools.
- Explain why, not just what. The code already shows what changed. Only you know the reason.
- One idea per commit. Small, focused commits are easier to review and to undo.
- Do not end the subject with a full stop. It wastes a character and adds nothing.
Before and after
An optional convention: type prefixes
Many teams add a short prefix to the subject, such as feat:, fix: or docs:. This style is called Conventional Commits. It makes history easy to scan, and it lets tools build changelogs automatically.
| Prefix | Use for |
|---|---|
feat: | A new feature |
fix: | A bug fix |
docs: | Documentation only |
refactor: | Code change that does not alter behavior |
test: | Adding or fixing tests |
chore: | Maintenance, tooling and dependencies |
It is a team decision. A consistent plain style beats a mixed use of prefixes.