A good Git commit message gives readers a quick description of the change and enough context to understand why it was made. Git’s documentation recommends a short subject line—no more than 50 characters as a good practice—then a blank line and a fuller explanation. The exact convention can vary by project, so check the repository’s contribution guide before applying a style mechanically.
What makes a commit message useful?
A commit message is most useful when it helps someone scanning the log identify the change, then helps a future developer understand the decision behind it. The subject provides the quick scan; the body carries reasoning and context that do not fit in a short line.
As an Amazon Associate I earn from qualifying purchases.
Git’s contributor documentation puts the purpose plainly: “The goal of your log message is to convey the why behind your change to help future developers.” See the Git project’s SubmittingPatches documentation.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →How should you write the subject line?
- Describe the change directly. Avoid vague filler that does not help a reader distinguish this commit from others.
- Keep it concise. Git’s git-commit documentation recommends a subject of no more than 50 characters as good practice, followed by a blank line and a more thorough description. It is guidance, not a universal requirement.
- Use the repository’s preferred voice and punctuation. Git project contributor guidance recommends imperative mood and no final period—for example, “Fix session timeout” rather than “Fixed session timeout.” Treat that as the Git project’s convention, not a law for every repository.
A useful test is whether the subject makes sense as a concise description of what the commit does. If it needs more explanation, put that explanation in the body rather than stretching the subject with filler.
What belongs in the body?
Use the body to explain why the change was made and include relevant constraints or non-obvious decisions. A reader may understand the code’s mechanics from the diff but still need to know what problem the change addresses or why one approach was chosen.
Keep the focus on the change and its rationale, rather than a diary of the author’s actions. The body should add context that a short subject cannot carry, not repeat the subject in longer form.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.When should you follow a project-specific convention?
Check the repository’s contribution instructions before choosing a format. A project may ask contributors to use particular prefixes, punctuation, subject lengths, or body details. Whether a convention is advisory or required depends on that project’s own guidance.
The Linux kernel’s Submitting Patches documentation is an example of guidance for a specific project environment. Apply its advice in that context; do not assume it defines the rules for unrelated repositories.
Quick Recap
Best Value
Rank #3
| Guidance | Subject convention | Body emphasis | Scope |
|---|---|---|---|
| Git commit documentation | A single short line of no more than 50 characters is recommended as good practice; separate fuller text with a blank line. | Provide a more thorough description when useful. | Git’s documented recommendation, not a mandatory limit for every project. |
| Git contributor documentation | Imperative mood and no final period are recommended. | Explain why the change was made so future developers can understand it. | Contributor guidance associated with the Git project. |
| Linux kernel patch documentation | Follow the kernel’s project-specific patch guidance. | Use the expectations described for kernel submissions. | Linux kernel project context; not a universal convention. |
A quick review before committing
- Read the repository’s contribution guide for any required format.
- Write a concise subject that identifies the change; use imperative mood and omit the final period if that is the project’s convention.
- If the subject needs more than a quick description, add a blank line and explain the reason, constraints, or decision in the body.
- Remove vague wording and action-by-action narration; keep the message useful to someone who encounters the commit later.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
