Create a good commit message

Commit messages are one of the most common ways that developers communicate with each other. As part of the GitHub flow, it is important that commit messages are informative and clearly written.

A well written commit message can save time and work in the long run by clearly communicating the intention of a commit. Commit messages are helpful to reviewers in a pull request, but later they will also be useful to people who are debugging code or reading a commit timeline.

Write a topical subject line

Good commit messages should have a subject line that briefly describes the change that was made and—when appropriate—why the change was necessary. A good subject line will enable a reader to understand the basic gist of a commit without needing to read the entire commit message.

This example subject line mentions what was changed:

Add a custom post type

An improved version of the subject line answers the question “What kind of custom post type?”:

Add a custom post type for portfolio content 

A further improved version of the subject line also answers the question “Why was this custom post type needed?”:

Add a custom post type for portfolio content to have its own format and RSS feed

If the commit is a part of a clearly-defined and named project, prefixing the commit with the project name can also be very helpful. For example:

Artist Theme Project: Add a custom post type for portfolio content to have its own format and RSS feed

If a subject line includes the word “and”—or in other way lists more than one item—the commit is probably too large and should be split into more than one commit.

Write an informative commit message

After the subject line, there should be an empty line before the rest of the commit message for readability.

The commit message should clearly communicate what was changed, the intent or goal of the change, and include details about complex abstractions. It is perfectly acceptable to spend more time crafting a commit message than writing the code for a commit. The length of the commit message might even be longer than the commit itself.

• Explain why a change was made: Add a clear explanation for the change to help a reader of the commit learn a new approach, or to help someone tracing a bug to understand the context of the problem better. This can help determine if the root cause of a bug is in that commit or further up the chain.
• Explain the cause and consequences of the problem: Knowing what caused a problem can avoid causing a similar problem again and understanding the consequences can help explain any erroneous behavior. For instance, during debugging, one can compare the consequences of a fixed problem with the new one.
• Explain how the commit achieves the goal: On occasions where it’s unclear, explaining the how benefits the reader (e.g. some high-level algorithm is encoded in the change) and highlights the importance of knowing it.

This example commit message provides the reader with an explanation of what was changed, why it was changed, and what goal was achieved:

Artist Theme Project: Add a custom post type for portfolio content to have its own format and RSS feed

Added a custom post type for portfolio content that has built-in custom fields for media, date, and price. The CPT also allows us to create an RSS feed by using core WordPress behavior rather than writing complicated code. 

GitHub will truncate any Pull Request title greater than 72 characters and replace the remaining characters with an ellipses (...). If a Pull Request only has one commit, GitHub will use the commit message as the Pull Request title, however the Pull Request title can be modified when opening the Pull Request to ensure that it’s less than 72 characters.

Read more about creating commits on GitHub