Guidelines for commit messages

This article provides guidelines for clear, concise and consistent commit messages.

Commit messages are stored in the version control system together with the source files a commit includes. They are intended to help developers to understand why a certain change was made and what was the goal of it.

I use these guidelines in my own projects unless there are already other, already existing guidelines to adhere to. For example, when an open source project already has its own CONTRIBUTING or a company has established existing standards.

The target audience are developers contributing to one of my projects, be it open source or commercial. It can also be of interest for people who are looking for a basis for their own guidelines.

This document is distributed under the CC BY 4.0 license.

General structure

Commit messages consist of the following parts:

  1. A reference to the issue the commit is related to
  2. A short description of the commit
  3. Optional: Further details describing what the commit includes and what its purpose

Issue reference

The issue reference already gives access to a lot of information about the background of the commit. This is particularly true if your issue descriptions use a high quality definition of ready.

The exact syntax for the issue reference depends on the issue tracker used. For GitHub and GitLab this would be #<number>. For example: #123

Many developer tools will convert this into a hypertext reference to the issue tracker.

Because git treats sentences starting with # as comments, you might have to add the following to your ~/.gitconfig:

    commentChar = ";"

Short description

The short descriptions with a verb in present tense describing the general nature of the commit. Common verbs are:

After the verb, add more details to describe the commit.

The short description can be considered to be a heading and therefor does not end with a dot


Further details

Sometimes the issue number and short description might not seem to be enough to understand to what end the commit has been made.

In such a case, add and empty line and then any text that seems helpful.

Use Markdown formatting to render lists, source code names etc.

This part can include:

Other styles

There are other style you might want to explore for further inspiration. Each style has a rationale why I do not use it (yet) in my projects. Your values and priorities may vary.