Commit Message
TL;DR
A commit message title should:- complete the sentence “When applied, this commit will …”
- start with a capital letter
- omit the full stop
- be at most 50 characters long
Structure
A commit message consists of a single subject line and may have a body. These must be separated by an empty line.
The subject should be no more than 50 characters long. It should start with an uppercase letter, and omit sentence-ending punctuation (e.g. a period).
The body may span multiple lines, but should be wrapped at 72 characters.
Consider writing it in the style of sembr. The body may be written in
markdown syntax, though beware, lines starting in # will be dropped,
as they are interpreted as line comments.
Trailers are structured key-value-pair metadata. Each trailer consists of a
key, followed by a colon, a single space, and a value. Commonly used keys
include Co-authored-by and Signed-off-by. They
should be placed at the very end of the commit body, separated from preceding
content by an empty line. Each trailer must be on its own line.
Semantics
The subject line should describe the what of the change. People will often skim a changelog by only looking at commit subjects, for example by using:
git log --oneline
The subject line should be written in the imperative. This is for
consistency with the commit messages that git generates, such as Merge branch, Revert, and Reapply.
Imperative verbs are also generally shorter than their past tense variant.
It might help to try and complete the sentence “When applied, this commit will”.
In repositories with many active contributors using Conventional Commits might be worth-while, as it makes skimming large amounts of commits easier.
The commit body should describe why the change was made. If more context is needed to describe the change itself, that may also go into the body.
If a commit was authored by multiple people, they should be credited using the Co-authored-by trailer.
Example
Refactor argument parsing This commit decouples the argument parsing logic from the built-in command definitions, laying the foundation for supporting user-defined commands. This change has no impact on existing functionality. Co-authored-by: David Millner <david.millner@sqrs.org> Co-authored-by: Laurent Piet <laurent@piet.fr>