Seven rules for good Git to submit messages

1. Separate the subject from the subject with a blank line
2. Limit subject lines to 50 characters
3. Capitalize subject line
4. Don't end the subject line with a period
5. Use imperative mood in subject line
6. Limit body to 72 characters
7. Explain with text

1. Separate the main body from the main body with a blank line

The git commit manual page reads:

Although not required, it is best to start submitting the message with a short (less than 50 characters) line, summarize the changes, then an empty line, and then a more comprehensive description. The text in the submission message up to the first blank line is considered the submission title, and the title is used throughout Git. For example, Git format patch (1) converts a submission to an email, including the title in the subject line and the rest of the submission in the body.

First, not every submission needs a subject and a body. Sometimes a single line is fine, especially when the change is so simple that no further context is required. For example:

Fix typo in introduction to user guide

If the reader wants to know what the typo is, simply look at the change itself, that is, use git show or git diff or git log -p.

If you submit something like this, you can use the following - m option git commit:

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

However, when the submission needs some explanation and context, a body needs to be written. For example:

Derezz the master control program

MCP turned out to be evil and had become intent on world domination.
This commit throws Tron's disc into MCP (causing its deresolution)
and turns it back into a chess game.

-m it's not easy to write a submission message with a body using this option. It is best to write the message in an appropriate text editor. If you haven't set up an editor for use with Git on the command line, read this section of Pro Git.

https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration

When browsing the log, it is meaningful to see the separation of subject and subject. This is the complete log entry:

$ git log
commit 42e769bdf4894310333942ffc5a15151222a87be
Author: Kevin Flynn <kevin@flynnsarcade.com>
Date:   Fri Jan 01 00:00:00 1982 -0200

 Derezz the master control program

 MCP turned out to be evil and had become intent on world domination.
 This commit throws Tron's disc into MCP (causing its deresolution)
 and turns it back into a chess game.

Now git log --oneline, it only prints out the subject line:

$ git log --oneline
42e769 Derezz the master control program

Alternatively, the git shortlog is grouped according to the submitted by the user, and a concise topic line is displayed again:

$ git shortlog
Kevin Flynn (1):
      Derezz the master control program

Alan Bradley (1):
      Introduce security program "Tron"

Ed Dillinger (3):
      Rename chess program to "MCP"
      Modify chess program
      Upgrade chess program

Walter Gibbs (1):
      Introduce protoype chess program

There are many other contexts in Git, in which the difference between the subject line and the body is introduced from the blank line in the middle. If there is no blank line, they will not work properly.

2. Subject lines are limited to 50 characters

50 characters is not a hard limit, but a rule of thumb. Keeping the subject lines at this length ensures that they are readable and forces the author to think for a moment to explain what is happening in the most concise way.

Tip: if it's hard to summarize, you may have submitted too many changes at one time. Strive for atomic submission (the subject of a separate post).

GitHub's UI fully understands these conventions. If the limit of 50 characters is exceeded, it will warn you:

Any subject line longer than 72 characters will be truncated with an ellipsis:

3. Subject line capitalization

All subject lines begin with a capital letter.

For example:

• Accelerate to 88 miles per hour

Replace:

• accelerate to 88 miles per hour

4. Don't end the subject line with a period

Trailing punctuation is not required in the subject line. In addition, keep it at 50 characters or less

example:

• Open the pod bay doors

Substitute:

• Open the pod bay doors.

5. Use imperative in the subject line

Imperative means "oral or written as if giving an order or instruction". Several examples:

• Clean your room
• Close the door
• Take out the trash

The order sounds a little rude. But it's perfect for Git to submit subject lines. One reason is that Git itself uses imperative when creating submissions on your behalf.

For example, the default message git merge created when using is:

Merge branch 'myfeature'

When using git revert:

Revert "Add the thing with the stuff"

This reverts commit cc87791524aedd593cff5a74532befe7ab69ce9d.

Or when you click the merge button on the GitHub pull request:

Merge pull request #123 from someuser/somebranch

Therefore, when writing a submission message in an imperative manner, you follow Git's own built-in conventions. For example:

• Refactor subsystem X for readability
• Update getting started documentation
• Remove deprecated methods
• Release version 1.0.0

• This submission will refactor subsystem X for readability and refactor subsystem X to improve readability
• This submission will update getting started documentation and update getting started documentation
• This submission will remove deprecated methods and delete deprecated methods
• This submission will release version 1.0.0 and release version 1.0.0
• This submission will merge pull request #123 from user/branch and merge pull request #123 from user/branch

6. Wrap the text in 72 characters

Git never wraps lines. When submitting the body of a message, you must pay attention to its right margin and wrap it manually.

It is recommended that you do this at 72 characters so that Git has enough space to indent the text while still keeping everything under 80 characters.

It is important to configure a good text editor such as Vim. For example, when writing Git submission, replace the text with 72 characters. Traditionally, however, ides have been poor at providing intelligent support for text wrapping in submitted messages.

7. Use the text to explain what and why and how

This submission from Bitcoin Core is a good example to explain what has changed and why:

commit eb0b56b19017ab5c16c745e6da39c53126924ed6
Author: Pieter Wuille <pieter.wuille@gmail.com>
Date:   Fri Aug 1 22:57:55 2014 +0200

   Simplify serialize.h's exception handling

   Remove the 'state' and 'exceptmask' from serialize.h's stream
   implementations, as well as related methods.

   As exceptmask always included 'failbit', and setstate was always
   called with bits = failbit, all it did was immediately raise an
   exception. Get rid of those variables, and replace the setstate
   with direct exception throwing (which also removes some dead
   code).

   As a result, good() is never reached after a failure (there are
   only 2 calls, one of which is in tests), and can just be replaced
   by !eof().

   fail(), clear(n) and exceptions() are just never called. Delete
   them.

Look at the complete differences and think about how much time the author has saved for other and future submitters by spending time providing this context here and now. If he doesn't, it may be lost forever.

In most cases, you can omit details on how to make changes. In this regard, the code is usually self-evident (if the code is too complex to be explained in prose, this is the purpose of source annotations). Just focus on first figuring out why the change was made - the way it worked before (and the problems in it), the way it works now, and why you decided to solve it your way

Thank you for your future defender may be yourself!