Git Primer

Published: at 01:00 AM

Git Commit Messages

Git commit messages can help you understand why something happened months or years ago for your collaborators or yourselves. It affects a project’s maintainability, and hence plays a critical role in a project’s long-term success.

This section we summarize some common techniques to write a healthy commit message. Of course there are variations on the styles and conventions adopted by different projects/orgs, you should pick one and stick to it as much as possible to reduce chaos and inconsistency.

A commit message is nothing but some plain texts explaining the changes you made. We can describe a git commit msg convention from several perspectives:

Fortunately, well-established conventions exist and you don’t need to re-invent the wheel.

Several rules of a great git commit msg 1

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize 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

E.g.

Summarize changes in around 50 characters or less

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 the commit 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); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.

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

If you use an issue tracker, put references to them at the bottom,
like this:

Resolves: #123
See also: #456, #789

Notes

  1. Not every commit msg needs both a subject and a body and sometimes a single line is fine for simple changes

    E.g.

    git commit -m "Fix typo in introduction to user guide"

  2. Commit msgs with a subject and a body are not easy to write with the -m option. You should configure an editor for use with git. You can also define a commit msg template in the git config like below to remind you of the proper format and style when creating a commit msg:

    E.g. Consider a template file at ~/.gitmessage.txt that looks like this

    Subject line (try to keep under 50 characters)

Multi-line description of commit,
feel free to be detailed.

[Ticket: X]

    To tell Git to use it as the default message that appears in your editor when you run git commit, set the commit.template configuration value:

    $ git config --global commit.template ~/.gitmessage.txt
$ git commit

  3. The blank line b/w the subject and body is essential and there’re a number of contexts in git like git log --oneline or git shortlog that the distinction b/w subject and body matter

  4. The 50 characters limit for the subject line forces the author to think about the most concise way to express his ideas. It also ensures that they are readable from the GitHub WebUI

  5. Your subject line should always be able to complete the following sentence:

    If applied, this commit will your subject line here

  6. When you write the git msg body if needed, be mindful about its right margin and wrap text at 72 characters. Consider to set up a good text editor that automatically wrap texts for you

    If you are using VSCode, the below settings can be a starting point:

    • Set VSCode as your default editor for git

      # '--wait': Wait for the files to be closed before returning.
$ git config --global core.editor "code --wait"

    • In your VSCode user settings.json, add the following wrap rule:

      "[git-commit]": {
    "editor.rulers": [
        72
    ],
    "editor.wordWrapColumn": 72,
    "editor.wordWrap": "wordWrapColumn",
    "editor.wrappingIndent": "same"
}

      More customizations can be found here.

Git Commands 2

References

Footnotes

  1. https://chris.beams.io/posts/git-commit/ ↩

  2. https://learngitbranching.js.org/?locale=en_US ↩

  3. https://git-scm.com/book/en/v2/Git-Basics-Undoing-Things ↩