Page History
This page describes how to phrase reasonable Writing reasonable git commit messages . We assume that you have already read and agreed in Commit rules!
| Info |
|---|
Reasonable commit messages facilitate:
And there are many other good reasons to write reasonable git commit messages |
| Table of Contents |
|---|
Intro
How to start the message
Below you will find seven good rules to write great commit messages. But before, please remember this specific Magnolia rule(s)
| Note |
|---|
The subject of the commit message MUST start with either
To start the message with
Do not commit code changes with QA! even if it is 'only' refactoring. Code changes must belong to a JIRA ticket. If you do not have a JIRA ticket, you must create a JIRA ticket. |
Use a well descriptive subject
...
helps fellow team members to read and understand a project's development history at a glance.
Following this facilitates several other activities, such as documentation, root-cause analysis or reverting changes.
Example
Subject | MAGNOLIA-6223 Add improved API for resource change observation |
General rule
As compiled by Chris Beams here and listed below, we follow the seven rules of a great git commit message. "Keep in mind: This has all been said before."
TL;DR
- Separate subject from body with a blank line
- Limit the subject line to 50 characters
- Capitalize the subject line
- Do not end the subject line with a period
- Use the imperative mood in the subject line
- Wrap the body at 72 characters
- Use the body to explain what and why vs. how
On top of these rules, mind the following Magnolia-specific guidelines:
| Tip |
|---|
|
...
|
...
|
...
|
...
|
...
The seven rules of a great git commit message
1. Separate subject from body with a blank line
From the git commit manpage:
...
Firstly, not every commit requires both a subject and a body. Sometimes a single line is fine, especially when the change is so simple that no further context is necessary. For example:
Fix typo in introduction to user guide
Nothing more need be said; if the reader wonders what the typo was, she can simply take a look at the change itself, i.e. use git show or git diff or git log -p.
If you're committing something like this at the command line, it's easy to use the-m switch to git commit:
$ git commit -m"Fix typo in introduction to user guide"
However, when a commit merits a bit of explanation and context, you need to write a body. For example:
Derezz the master control program
MCP turned out to be evil and had become intent on world domination.
This commit throws Tron's disc into MCP (causing its deresolution)
and turns it back into a chess game.
This is not so easy to commit this with the -m switch. You really need a proper editor. If you do not already have an editor set up for use with git at the command line, read this section of Pro Git.
In any case, the separation of subject from body pays off when browsing the log. Here's the full log entry:
$ git log
commit 42e769bdf4894310333942ffc5a15151222a87be
Author: Kevin Flynn <kevin@flynnsarcade.com>
Date: Fri Jan 01 00:00:00 1982 -0200
Derezz the master control program
MCP turned out to be evil and had become intent on world domination.
This commit throws Tron's disc into MCP (causing its deresolution)
and turns it back into a chess game.
And now git log --oneline, which prints out just the subject line:
$ git log --oneline
42e769 Derezz the master control program
Or, git shortlog, which groups commits by user, again showing just the subject line for concision:
$ git shortlog
Kevin Flynn (1):
Derezz the master control program
Alan Bradley (1):
Introduce security program "Tron"
Ed Dillinger (3):
Rename chess program to "MCP"
Modify chess program
Upgrade chess program
Walter Gibbs (1):
Introduce protoype chess program
There are a number of other contexts in git where the distinction between subject line and body kicks in—but none of them work properly without the blank line in between.
2. Limit the subject line to 50 characters
| Note |
|---|
The advice to limit the subject line to 50 characters is well-intentioned - it seems very hard to follow. Check the git log of main, ui and other Magnolia projects and try to find commit message subjects which use not more than 50 characters. To keep the commit message subject clean and short is very important, but very often it seems impossible to follow the "50 characters rule". If you can manage not to use more than 72 (see rule #6) - seems fine. (Personal note from Christoph Meier) |
50 characters is not a hard limit, just a rule of thumb. Keeping subject lines at this length ensures that they are readable, and forces the author to think for a moment about the most concise way to explain what's going on.
...
So shoot for 50 characters, but consider 69 the hard limit.
3. Capitalize the subject line
This is as simple as it sounds. Begin all subject lines with a capital letter.
...
- accelerate to 88 miles per hour
4. Do not end the subject line with a period
Trailing punctuation is unnecessary in subject lines. Besides, space is precious when you're trying to keep them to 50 chars or less.
...
Instead of:
- Open the pod bay doors.
5. Use the imperative mood in the subject line
Imperative mood just means "spoken or written as if giving a command or instruction". A few examples:
...
For example, the default message created when using git merge reads:
Merge branch 'myfeature'
And when using git revert:
Revert "Add the thing with the stuff"
This reverts commit cc87791524aedd593cff5a74532befe7ab69ce9d.
Or when clicking the "Merge" button on a GitHub pull request:
Merge pull request #123 from someuser/somebranch
So when you write your commit messages in the imperative, you're following git's own built-in conventions. For example:
...
Remember: Use of the imperative is important only in the subject line. You can relax this restriction when you're writing the body.
6. Wrap the body at 72 characters
Git never wraps text automatically. When you write the body of a commit message, you must mind its right margin, and wrap text manually.
...
A good text editor can help here. It's easy to configure Vim, for example, to wrap text at 72 characters when you're writing a git commit. Traditionally, however, IDEs have been terrible at providing smart support for text wrapping in commit messages (although in recent versions, IntelliJ IDEA has finally gotten better about this).
7. Use the body to explain what and why vs. how
This commit from Bitcoin Core is a great example of explaining what changed and why:
commit eb0b56b19017ab5c16c745e6da39c53126924ed6
Author: Pieter Wuille <pieter.wuille@gmail.com>
Date: Fri Aug 1 22:57:55 2014 +0200
Simplify serialize.h's exception handling
Remove the 'state' and 'exceptmask' from serialize.h's stream
implementations, as well as related methods.
As exceptmask always included 'failbit', and setstate was always
called with bits = failbit, all it did was immediately raise an
exception. Get rid of those variables, and replace the setstate
with direct exception throwing (which also removes some dead
code).
As a result, good() is never reached after a failure (there are
only 2 calls, one of which is in tests), and can just be replaced
by !eof().
fail(), clear(n) and exceptions() are just never called. Delete
them.
Take a look at the full diff and just think how much time the author is saving fellow and future committers by taking the time to provide this context here and now. If he didn't, it would probably be lost forever.
In most cases, you can leave out details about how a change has been made. Code is generally self-explanatory in this regard (and if the code is so complex that it needs to be explained in prose, that's what source comments are for). Just focus on making clear the reasons you made the change in the first place—the way things worked before the change (and what was wrong with that), the way they work now, and why you decided to solve it the way you did.
References
Overview
Content Tools