Instantly share code, notes, and snippets.

Embed
What would you like to do?
Commit message guidelines

Commit Message Guidelines

Short (72 chars or less) summary

More detailed explanatory text. Wrap it to 72 characters. The blank
line separating the summary from the body is critical (unless you omit
the body entirely).

Write your commit message in the imperative: "Fix bug" and not "Fixed
bug" or "Fixes bug." This convention matches up with commit messages
generated by commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too.
- Typically a hyphen or asterisk is used for the bullet, followed by a
  single space. Use a hanging indent.

Example for a commit message

Add CPU arch filter scheduler support

In a mixed environment of…

A properly formed git commit subject line should always be able to complete the following sentence

If applied, this commit will <your subject line here>

Rules for a great git commit message style

  • Separate subject from body with a blank line
  • Do not end the subject line with a period
  • Capitalize the subject line and each paragraph
  • Use the imperative mood in the subject line
  • Wrap lines at 72 characters
  • Use the body to explain what and why you have done something. In most cases, you can leave out details about how a change has been made.

Information in commit messages

  • Describe why a change is being made.
  • How does it address the issue?
  • What effects does the patch have?
  • Do not assume the reviewer understands what the original problem was.
  • Do not assume the code is self-evident/self-documenting.
  • Read the commit message to see if it hints at improved code structure.
  • The first commit line is the most important.
  • Describe any limitations of the current code.
  • Do not include patch set-specific comments.

Details for each point and good commit message examples can be found on https://wiki.openstack.org/wiki/GitCommitMessages#Information_in_commit_messages

References in commit messages

If the commit refers to an issue, add this information to the commit message header or body. e.g. the GitHub web platform automatically converts issue ids (e.g. #123) to links referring to the related issue. For issues tracker like Jira there are plugins which also converts Jira tickets, e.g. Jirafy.

In header:

[#123] Refer to GitHub issue…
CAT-123 Refer to Jira ticket with project identifier CAT…

In body:

…
Fixes #123, #124

Sources

@GeorgeGkas

This comment has been minimized.

Show comment
Hide comment
@GeorgeGkas

GeorgeGkas Jan 6, 2018

With the current version (revision #2) the subject line is ignored by git if it includes an issue id. The second revision introduces a style change in subject format that proposes the use of #<IssueID> at the start of the subject. However, git ignore lines that start with # character thus making the body of the commit the actual subject. I propose to switch back to revision #1 or introduce a different style. We can add the referring issue id to an independent line after the subject. Something like:

Short (72 chars or less) summary

Refer to issue #<IssueId>

More detailed explanatory text. Wrap it to 72 characters. The blank
line separating the summary from the body is critical (unless you omit
the body entirely).

Write your commit message in the imperative: "Fix bug" and not "Fixed
bug" or "Fixes bug." This convention matches up with commit messages
generated by commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too.
- Typically a hyphen or asterisk is used for the bullet, followed by a
  single space. Use a hanging indent.

GeorgeGkas commented Jan 6, 2018

With the current version (revision #2) the subject line is ignored by git if it includes an issue id. The second revision introduces a style change in subject format that proposes the use of #<IssueID> at the start of the subject. However, git ignore lines that start with # character thus making the body of the commit the actual subject. I propose to switch back to revision #1 or introduce a different style. We can add the referring issue id to an independent line after the subject. Something like:

Short (72 chars or less) summary

Refer to issue #<IssueId>

More detailed explanatory text. Wrap it to 72 characters. The blank
line separating the summary from the body is critical (unless you omit
the body entirely).

Write your commit message in the imperative: "Fix bug" and not "Fixed
bug" or "Fixes bug." This convention matches up with commit messages
generated by commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too.
- Typically a hyphen or asterisk is used for the bullet, followed by a
  single space. Use a hanging indent.

@camh-

This comment has been minimized.

Show comment
Hide comment
@camh-

camh- Jan 11, 2018

To further support @GeorkeGkas's comment, the summary line is one of the more important parts to get right and with limited space, using it for metadata (the issue ID) is taking away from that limited space.

Most metadata is put at the end of a commit message in a rfc822 header line format.

Fixes: #1234
Signed-off-by: Me me@example.com
Tested-by: You you@example.com
...

If you're just referencing an issue:
Issues: #1234

Just my 2c.

camh- commented Jan 11, 2018

To further support @GeorkeGkas's comment, the summary line is one of the more important parts to get right and with limited space, using it for metadata (the issue ID) is taking away from that limited space.

Most metadata is put at the end of a commit message in a rfc822 header line format.

Fixes: #1234
Signed-off-by: Me me@example.com
Tested-by: You you@example.com
...

If you're just referencing an issue:
Issues: #1234

Just my 2c.

@sorcerykid

This comment has been minimized.

Show comment
Hide comment
@sorcerykid

sorcerykid Jan 22, 2018

What is the generally accepted practice if a commit contains numerous unrelated changes that cannot be described succinctly in just 50 characters?

For example, if a recent project involves patching a vulnerability in the login handler, removing unused image and sound files, refactoring code and adding better comments, improving performance of the main event loop, fixing bugs in the collision detection algorithm, etc. There is no possible way all of that can fit into a subject line. Yet a generic subject line like "Addressed a lot of lingering issues (see below)" doesn't conform to the conventions described above either.

Any advice would be greatly appreciated. Thanks!

sorcerykid commented Jan 22, 2018

What is the generally accepted practice if a commit contains numerous unrelated changes that cannot be described succinctly in just 50 characters?

For example, if a recent project involves patching a vulnerability in the login handler, removing unused image and sound files, refactoring code and adding better comments, improving performance of the main event loop, fixing bugs in the collision detection algorithm, etc. There is no possible way all of that can fit into a subject line. Yet a generic subject line like "Addressed a lot of lingering issues (see below)" doesn't conform to the conventions described above either.

Any advice would be greatly appreciated. Thanks!

@djanowski

This comment has been minimized.

Show comment
Hide comment
@djanowski

djanowski Jan 24, 2018

What to do when including long URLs in the body?

djanowski commented Jan 24, 2018

What to do when including long URLs in the body?

@robertpainsi

This comment has been minimized.

Show comment
Hide comment
@robertpainsi
Owner

robertpainsi commented Feb 18, 2018

@GeorgeGkas, @camh-, thanks, updated!

@robertpainsi

This comment has been minimized.

Show comment
Hide comment
@robertpainsi

robertpainsi Feb 18, 2018

@djanowski, you can either

  1. put them on it's own line
Fetching an object is done by using the technique explained at
https://www.url.com/some/very/long/url/that/easily/exceeds/72/characters/per/line
and…

(a line should only exceed 72 characters if the line can't be split. There are also exceptions to this rule, e.g. if you're using code in the commit message)

  1. or reference them
Fetching an object is done by using the technique explained at [1] and…
…
[1] https://www.url.com/some/very/long/url/that/easily/exceeds/72/characters/per/line

Since in many cases the reference is embedded in a paragraph, I prefer the second option. It keeps the line formatting clean and doesn't interrupt your reading.

Owner

robertpainsi commented Feb 18, 2018

@djanowski, you can either

  1. put them on it's own line
Fetching an object is done by using the technique explained at
https://www.url.com/some/very/long/url/that/easily/exceeds/72/characters/per/line
and…

(a line should only exceed 72 characters if the line can't be split. There are also exceptions to this rule, e.g. if you're using code in the commit message)

  1. or reference them
Fetching an object is done by using the technique explained at [1] and…
…
[1] https://www.url.com/some/very/long/url/that/easily/exceeds/72/characters/per/line

Since in many cases the reference is embedded in a paragraph, I prefer the second option. It keeps the line formatting clean and doesn't interrupt your reading.

@robertpainsi

This comment has been minimized.

Show comment
Hide comment
@robertpainsi

robertpainsi Feb 18, 2018

@sorcerykid, http://whatthecommit.com/ (refresh a few times until you find the commit message that suites your changes 😉)

There isn't really an "accepted practice" here. Maybe you still can split your changes into multiple commits?
Leaving following note here:

Commit Often, Perfect Later, Publish Once

Owner

robertpainsi commented Feb 18, 2018

@sorcerykid, http://whatthecommit.com/ (refresh a few times until you find the commit message that suites your changes 😉)

There isn't really an "accepted practice" here. Maybe you still can split your changes into multiple commits?
Leaving following note here:

Commit Often, Perfect Later, Publish Once

@GeorgeGkas

This comment has been minimized.

Show comment
Hide comment
@GeorgeGkas

GeorgeGkas Mar 11, 2018

I want to propose a possible improvement in References in commit messages section. There are times, not very often but exists, that a commit refers to more than one issue. Most of the times, when this happens, a commit will not refer to more than 2 -maybe 3- issues. To be able to reference multiple issues in the header I propose the following format:

[#123, #879] Refer to GitHub issue…

I would like to read what is your reaction to this update. 😄

GeorgeGkas commented Mar 11, 2018

I want to propose a possible improvement in References in commit messages section. There are times, not very often but exists, that a commit refers to more than one issue. Most of the times, when this happens, a commit will not refer to more than 2 -maybe 3- issues. To be able to reference multiple issues in the header I propose the following format:

[#123, #879] Refer to GitHub issue…

I would like to read what is your reaction to this update. 😄

@rsp

This comment has been minimized.

Show comment
Hide comment
@rsp

rsp Apr 17, 2018

@robertpainsi 👍 Excellent guideline, thanks for sharing that. I would only have one comment that I don't generally recommend putting any references to issues or pull requests into the commit message subjects (first line) because I like them to strictly adhere to the "Do something" style with no information that is not meaningful by itself, especially when viewed outside of GitHub like in the command line, or in the case of moving the project to other git hosting, or forking, in which case the issue/PR numbers will be invalid. For that reason I recommend putting those always in the body of the commit message instead. Other than that I think your guideline is really good and I might add some of your commit message rules to my guideline if you don't mind. 😁

rsp commented Apr 17, 2018

@robertpainsi 👍 Excellent guideline, thanks for sharing that. I would only have one comment that I don't generally recommend putting any references to issues or pull requests into the commit message subjects (first line) because I like them to strictly adhere to the "Do something" style with no information that is not meaningful by itself, especially when viewed outside of GitHub like in the command line, or in the case of moving the project to other git hosting, or forking, in which case the issue/PR numbers will be invalid. For that reason I recommend putting those always in the body of the commit message instead. Other than that I think your guideline is really good and I might add some of your commit message rules to my guideline if you don't mind. 😁

@anxiousinc

This comment has been minimized.

Show comment
Hide comment
@anxiousinc

anxiousinc Jun 26, 2018

Thank you so much for the knowledge.

anxiousinc commented Jun 26, 2018

Thank you so much for the knowledge.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment