How to write a git commit message

How to write a git commit
message
2018, Miroslav Merinsky
miroslav.merinsky@gmail.com

Why it is so important?
The well-crafted git commit message is the best way to communicate context
about a change to fellow developers. A diff will tell you what changed, but only the
commit message can properly tell you why.
“Re-establishing the context of a piece of code is wasteful. We can’t avoid it completely, so our
efforts should go to reducing it as much as possible. Commit messages can do exactly that and as
a result, a commit message shows whether a developer is a good collaborator.”
Peter
Hutterer

How a commit message should look like?
$ git log
commit 42e769bdf4894310333942ffc5a15151222a87be
Author: Miroslav Merinsky <miroslav.merinsky@gmail.com>
Date: Fri Jan 01 00:00:00 2018 -0200
Subject - summarize changes; 50 characters or less; capitalize; no period; use imperative
Explanation - more detailed explanation text, if necessary; 72 characters
List
- list item I
- list item II
Resolves: #20147

Explanation
Focus on why you are making this change as opposed to how (in meaning source
code changes).
Describe what original problem is.
Do not assume the code is self-evident/self-documenting.
Describe any limitations of the current code.
Side effects or other unintuitive consequences?

Commit content
Only one logical change
- quicker and easier to review and identify potential flaws
- easier troubleshooting
Avoid mixing whitespace changes with functional code changes
Avoid mixing two unrelated functional changes
Avoid sending large new features in a single giant commit
- a new feature often entail refactoring existing code - any refactoring is done in
commits which are separate from those implementing the new feature
- newly written code can often be split up into multiple pieces

Example #1
$ git log
commit 42ffc5a15151222a87be42e769bdf48943103339
Author: John Dow <john.dow@gmail.com>
Date: Fri Jan 01 00:00:00 2018 -0200
Fix typo in introduction to user guide

Example #1 - explanation
$ git log
commit 42ffc5a1515122245545414a87be42e7...
Date: Fri Jan 01 00:00:00 2018 -0200
Fix typo in introduction to user guide
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.

Example #2
$ git log
commit a87be42e769bd42ffc5a15151222f48943103339
Date: Fri Jan 22 00:00:00 2017 -0200
more fixes for broken stuff

$ git log
commit a87be42e769bd42ffc5a15151222f4...
Date: Fri Jan 22 00:00:00 2017 -0200
more fixes for broken stuff
The first subject letter should be
capital.
An imperative not used.
The “more fixes” evokes that there is
more than one logical change.

Example #3
$ git log
Date: Fri Jan 22 00:00:00 2017 -0200
Fix missing import in compute/utils.py
Fixes bug 1014829

$ git log
Date: Fri Jan 22 00:00:00 2017 -0200
Fix missing import in compute/utils.py
Fixes bug 1014829
Unclear. This does not mention what
imports, where it is missing and why it
is needed.

Example #3 - corrected
$ git log
Date: Fri Jan 22 00:00:00 2017 -0200
Add missing import of 'exception' in compute/utils.py
The compute/utils.py makes a reference to exception.NotFound,
however exception has not been imported.
Fixes bug 1014829

Example #4
$ git log
Date: Fri Jan 22 00:00:00 2017 -0200
Present correct ec2id format for volumes and snaps
Fixes bug #1013765
Change-Id: I5e574f8e60d091ef8862ad814e2c8ab993daa366

$ git log
Date: Fri Jan 22 00:00:00 2017 -0200
Present correct ec2id format for volumes
and snaps
Fixes bug #1013765
Change-Id:
I5e574f8e60d091ef8862ad814e2c8ab993daa366
This does not mention what the current
(broken) format is, nor what the new
fixed format is.

$ git log
Date: Fri Jan 22 00:00:00 2017 -0200
Present correct ec2id format for volumes and snaps
During the volume uuid migration, done by changeset 784444,
ec2 id formats for volumes and snapshots was dropped and is
now using the default instance format (i-xb5). These need
to be changed back to vol-xb5 and snap-xb5.
Fixes bug #1013765
Change-Id: I5e574f8e60d091ef8862ad814e2c8ab993daa366

Example #5
$ git log
Date: Fri Jan 22 00:00:00 2017 -0200
Add libvirt min version check
Fixes LP Bug #1012689

$ git log
Date: Fri Jan 22 00:00:00 2017 -0200
Add libvirt min version check
This commit message is merely
documenting what was done, and not
why it was done.

$ git log
Date: Fri Jan 22 00:00:00 2017 -0200
Add libvirt version check, min 0.9.7
The commit 47a41r7 introduced use of the 'reset' API
which is only available in libvirt 0.9.7 or newer. Add a check
performed at startup of the compute server against the libvirt
connection version. If the version check fails the compute
service will shutdown.

Example #6
$ git log
Date: Fri Jan 22 00:00:00 2017 -0200
Update default policies for KVM guest PIT & RTC timers
The default policies for the KVM guest PIT and RTC timers
are not very good at maintaining reliable time in guest
operating systems. In particular Windows 7 guests will
often crash with the default KVM timer policies, and old
Linux guests will have very bad time drift
Set the PIT such that missed ticks are injected at the
normal rate, ie they are delayed
This corresponds to the following libvirt XML
<clock offset='utc'>
<timer name='pit' tickpolicy='delay'/>
<timer name='rtc' tickpolicy='catchup'/>
</clock>
This should provide a default configuration that works
acceptably for most OS types. In the future this will
likely need to be made configurable per-guest OS type.
Closes-Bug: #1011848

It describes what the original problem
is (bad KVM defaults)
It describes the functional change
being made (the new PIT policies)
It describes what the result of the
change is (new the XML args)
It describes scope for future
improvement (the possible per-OS
type config)
It uses the Closes-Bug notation
$ git log
Date: Fri Jan 22 00:00:00 2017 -0200
The default policies for the KVM guest PIT and RTC timers
are not very good at maintaining reliable time in guest
operating systems. In particular Windows 7 guests will
often crash with the default KVM timer policies, and old
Linux guests will have very bad time drift
Set the PIT such that missed ticks are injected at the
normal rate, ie they are delayed
This corresponds to the following libvirt XML
<clock offset='utc'>
<timer name='pit' tickpolicy='delay'/>
<timer name='rtc' tickpolicy='catchup'/>
</clock>
This should provide a default configuration that works
acceptably for most OS types. In the future this will
likely need to be made configurable per-guest OS type.
Closes-Bug: #1011848

Example #7
$ git log
Date: Fri Jan 22 05:13:05 2017 -0200
commit 5a15151222f4894a87be42e769bd42ffc5a15489
Date: Fri Jan 23 12:08:02 2017 -0200
Add support for configuring libvirt VM clock and timers

$ git log
commit a87be42e769bd42ffc5a15151222...
Date: Fri Jan 22 05:13:05 2017 -0200
Update default policies for KVM guest PIT &
RTC timers
commit 5a15151222f4894a87be42e769bd42...
Date: Fri Jan 23 12:08:02 2017 -0200
Add support for configuring libvirt VM
clock and timers
Together these two changes provide
support for configuring the KVM guest
timers.
The introduction of the new APIs for
creating libvirt XML configuration have
been clearly separated from the
change to the KVM guest creation
policy, which uses the new APIs.

Example #8
$ git log
Date: Fri Jan 22 05:13:05 2017 -0200
Refactor libvirt create calls
* minimizes duplicated code for create
* makes wait_for_destroy happen on shutdown instead of undefine
* allows for destruction of an instance while leaving the domain
* uses reset for hard reboot instead of create/destroy
* makes resume_host_state use new methods instead of hard_reboot
* makes rescue/unrescue not use hard reboot to recreate domain
Change-Id: I2072f93ad6c889d534b04009671147af653048e7

$ git log
commit a87be42e769bd42ffc5a15151222...
Date: Fri Jan 22 05:13:05 2017 -0200
Refactor libvirt create calls
* minimizes duplicated code for create
* makes wait_for_destroy happen on
shutdown instead of undefine
* allows for destruction of an instance
while leaving the domain
* uses reset for hard reboot instead of
create/destroy
* makes resume_host_state use new methods
instead of hard_reboot
* makes rescue/unrescue not use hard
reboot to recreate domain
Change-Id:
I2072f93ad6c889d534b04009671147af653048e7
There are at least two independent
changes made in this commit.
There is no compelling reason why
these changes needed to be made at
the same time and clear description
why.

How to write a git commit message

Recommended

Recommended

More Related Content

Similar to How to write a git commit message

Similar to How to write a git commit message (20)

Recently uploaded

Recently uploaded (20)

How to write a git commit message

Editor's Notes