How to write the perfect commit message
Subject and body, imperative, the why instead of the obvious. An evergreen guide to commit messages that still help six months later.
Why the commit message matters so much
Code says what happens. The commit message says why. Six months later nobody remembers the reason for a change, and that is exactly when a good message saves hours. A commit message is not an annoying required field but a note to your future team and to yourself.
The structure: subject and body
A good commit message has two parts. The first line is the subject, a concise summary. After it, separated by a blank line, comes the optional body with the details. Many tools and interfaces show only the subject, so it has to make sense on its own.
Rules for the subject
- Keep it short, as a rule of thumb under about fifty characters.
- Write in the imperative, so "Fix crash on login" rather than "Fixed crash". That matches how Git itself phrases things.
- No full stop at the end, it is a heading, not a sentence.
- Say what the commit does, not how it does it. The how is in the code.
When you need a body
For a trivial change the subject is enough. As soon as a decision is behind it, that belongs in the body. Explain why the change was needed, which alternatives you rejected and what someone reading the commit later needs to know. Do not repeat the obvious, provide the context that is not in the code.
A good example
Limit upload size to ten megabytes
Large uploads filled up the worker and blocked
other requests. The limit covers all real cases
and protects the service.Conventions in a team
In many projects a fixed format has taken hold, such as a prefix like feat, fix or docs before the subject. Such conventional commits help to process the history automatically and generate changelogs. Whether you use that depends on the team. What matters most is consistency. A project where all messages follow the same pattern reads far more easily.
How Spire helps
Spire shows subject and body separately, so the first line stays concise and the details have room. Because you can stage individual lines in Spire, it is easier to build small, focused commits, and focused commits are much clearer to describe. A good message actually starts with a commit that does only one thing.
Short checklist
- Subject short, imperative, no full stop.
- Body explains the why, not the obvious.
- One commit, one thing.
- Follow a single format within the team.