This is an old revision of the document!
Git Commit Message
This document provides guidelines on how to write a well-formed commit message
when developing for MantisBT.
See below for further details
Maximum length 72 characters, try to stay under 50 if possible.
Describe the change in the patch, not the bug or effects/benefits.
No trailing period.
Optional if the Summary is self explanatory
Always add a blank line between summary and description
Wrap lines at 72 characters
Background information and details on the change (i.e *why*, not *how*)
Description must be understandable for everyone, not just for you (also 6 months down the line !)
Optional, but most commits should reference an issue in the bugtracker
, formatted for use by the Source Integration
Remember to give credit when it's due (
git commit –author= or at least a reference in the description)
This is somewhat out of scope of this document, but nevertheless related information, so here goes.
Remember that each commit should cover only one single logical/functional change.
Mix whitespace changes with functional code changes
The whitespace changes will obscure the important functional changes, making it harder for a reviewer to correctly determine whether the change is correct.
Solution: Create 2 commits, first one with the whitespace changes, then one with the functional changes.
Mix two unrelated functional changes
Again the reviewer will find it harder to identify flaws if two unrelated changes are mixed together. If it becomes necessary to later revert a broken commit, the two unrelated changes will need to be untangled, with further risk of bug creation.
Bundle large new features in a single giant commit
If a code change can be broken down into a sequence of patches/commits, then it should be split (e.g. commits with API
changes, then commits with GUI
Details and Explanations
A good commit message should basically answer three questions about a patch:
Why is it necessary?
It may fix a bug, it may add a feature, it may improve performance, reliabilty, stability, or just be a change for the sake of correctness.
How does it address the issue?
For short obvious patches this part can be omitted, but it should be a high level description of what the approach was.
What effects does the patch have?
(In addition to the obvious ones, this may include benchmarks, side effects, etc.)
The Summary line is used all over Git, oftentimes in truncated form if it is too long.
It should be kept under 50 characters if possible, but no more than 72 characters long.
Using a long Summary may make it more difficult to understand what the commit is about when using one of the below (and other) commands.
Examples of where it ends up:
git log –pretty=oneline shows a terse history mapping containing the commit id and the summary
git rebase –interactive provides the summary for each commit in the editor it invokes
git format-patch, git send-email, and related tools use it as the subject for emails
git reflog, provides a local history intended to help recovery from stupid mistakes
uses the summary in various places in their user interface
Remember to always add a blank line between Summary and Description.
Why 72 chars
git log doesn’t do any special special wrapping of the commit messages.
With the default pager of
less -S, this means long lines will flow far off the edge of the screen, making them difficult to read. On an 80 column terminal, if we subtract 4 columns for the indent on the left and 4 more for symmetry on the right, we’re left with 72 columns.
git format-patch –stdout generates emails from commits using the Description for the message body.
Good email netiquette dictates we wrap our plain text emails such that there’s room for a few levels of nested reply indicators without overflow in an 80 column terminal.
These guidelines were mainly inspired by