The Art of writing great Commit Messages

The Art of writing great Commit Messages

Person working at a computer

All of us are probably familiar with the most commonly used Version Control System, Git. In this blog, I just want to highlight some key points that we should follow while using Git as a team.

 

We have always heard the saying:

Perfect variable and function names do not require any comments or documentation.

This statement is so true in software development that if followed, makes the code much more understandable and thus, maintainable.

 

But in addition to this, I also believe:

Your commit messages should be so informative that you don’t have to open the altered files to view the modifications.

 

Why use better commit message standards?

The text up to the first blank line in a commit message is treated as the commit title, and that title is used throughout Git.

Git-format-patch(1) turns a commit into email, and it uses the title on the Subject line and the rest of the commit in the Body.

This simplifies the understanding of the changes that took place in any particular commit.

A commit message shows whether a developer is a good collaborator.

 

The contributors to repositories know that a well-crafted Git commit message is the best way to communicate context about a change to fellow developers (and indeed to their future selves).

Understanding why something happened months or years ago becomes not only possible but efficient.

A diff will tell you what changed, but only the commit message can properly tell you why.

 

A project’s long-term success majorly relies on its maintainability, and a maintainer has few tools more powerful than his project’s log. It’s worth investing time to understand and learn how to care for one properly. What may be a hassle at first soon becomes a habit, and eventually a source of pride and productivity for all involved.

Most programming languages have traditional conventions as to what constitutes idiomatic style, i.e. naming, formatting and so on. There are variations on these conventions, but most developers agree that picking one and sticking to it is better than the chaos that ensues when everybody does their own thing.

 

Thumb rules for writing commit messages:

  1. Separate subject from the body with a blank line
  2. Limit the subject line to 50 characters (Soft rule)
  3. Capitalise the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how

 

1. Separate subject from the body with a blank line

From the Git Commit ManPage:

Though not required, it’s a good idea to begin the commit message with a single short (less than 50 characters) line summarising the change, followed by a blank line and then a more thorough description.

The text up to the first blank line in a commit message is treated as the commit title, and that title is used throughout Git.

Not every commit needs to have both Subject and Body. Sometimes a simple line works just as well.

Fix typo in README file

For this, we can directly use the commit command with -m option

$ git commit -m “Fix typo in README file”

But when you have some commit that cannot be explained with a simple line, we might need to consider the Subject and Body format.

Fix tests in Settings Factory for release 2.1.3

Tests were failing due to new parameter added in the Settings Factory.

Changes implemented:
    1. Mock object created for logger
    2. Pass logger with verbose level to the factory

git log --oneline will print out just the subject line:

$ git log --oneline
42e852 Fix tests in Settings Factory for release 2.1.3
fd62a8 Insert level parameter in Logger Factory

 

2. Limit the subject line to 50 characters

This is not a mandated rule, just a thumb rule. This limit of 50 characters ensures the subject is readable and precise. This limit allows a user to think any concise alternative for the commit message.

Subject line above 72 characters will be truncated with ellipses in the GitHub GUI.

So, in short:

Soft limit: 50 characters

Hard Limit: 72 characters

 

3. Capitalise the subject line

This rule is simple and can be easily followed. 

Use:

Fix typo in README file

Instead of:

fix typo in README file

 

4. Do not end the subject line with a period

Save space! Why do we want to have trailing punctuation in the subject line for no reason?

Just like we never add a period in the Subject line while writing an email, we should do the same by avoiding it in the commit messages.

Use:

Fix typo in README file

Instead of:

Fix typo in README file.

 

5. Use the imperative mood in the subject line

An imperative tone is defined as: “spoken or written as if giving a command or instruction”. 

A few examples:

  • Close the door
  • Go to school
  • Prepare some food

This might sound weird at first, but if we look closely, this is how Git itself uses the imperative tone for all messages.

E.g.

Merge branch develop

Merge pull request #2548 from feature/branchName

Likewise, we should use:

Fix sign-out bug in Accounts Screen

Change parameter default values

Instead of:

Fixed sign-out bug in Account Screen

Changed parameter default values

A simple way to achieve this tone is to complete the following sentence:

If applied, this commit will your commit message

E.g.

If applied, this commit will fix the sign-out bug in the Account Screen

 

6. Wrap the body at 72 characters

The text we type is not truncated automatically by Git. We must wrap the text at 72 characters since it is printed with indentation by git which shall include some extra characters (usually 4 to 8).

Git Commit message format comparison

 

7. Use the body to explain what and why vs. how

It’s extremely hard to understand what was going through a colleagues mind (or even your own) 6 months after the code has been committed. Providing the context allows understanding why the code was changed, not simply how.

This tells reviewers of your pull request what to expect in the commit, allowing them to more easily identify and point out unrelated changes.

How does it address the issue?

Describe, at a high level, what was done to affect change. Some examples:

Introduce a status flag to increase search speed

OR

Remove implicit parameters, which is causing OutOfBounds exception

If your change is obvious, you may omit to address this question.

What side effects does this change have?

This is the most important question to answer, as it can point out problems where you are making too many changes in one commit or branch. One or two bullet points for related changes may be okay, but five or six are likely indicators of a commit that is doing too many things.

 

Code is more often read than written!

 

Additional:

Issue Reference:

Fix sign-out bug in Accounts Screen

This ensures that the clicking on Sign-Out button clears all user defaults.

It helps to create a fresh state for the next user login.

Closes https://github.com/user/project/issues/3725
  • Use the keyword Fixes if your commit fixes a bug, or use Closes if it adds a feature/enhancement.
  • In some situations, the difference between Fixes and Closes may be very small and subjective.
  • If a specific issue may lead to an unintended behaviour from the user or from the program it should be considered a bug and should be addressed with Fixes.
  • If an issue is labelled with type/bug you should always use Fixes. For all other issues use Closes.
  • Should use full URL to the issue.
  • There should be a single space between the Fixes or Closes and the URL.

 

Summary:

# 50-character subject line
#
# 72-character wrapped longer description. This should answer:
#
# * Why was this change necessary?
# * How does it address the problem?
# * Are there any side effects?
#
# Include a link to the ticket, if any.

As Specified by Git:

Short (50 chars or less) summary of changes

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Further paragraphs come after blank lines.
  - Bullet points are okay, too
  - Typically a hyphen or asterisk is used for the bullet, preceded by a
    single space, with blank lines in between, but conventions vary here
Please follow and like: