Standards for Git commit messages

Table of contents

Hi!

I’m trying to improve my Git skills and, while I was searching about standards and good practices, especially on how to write a good commit message, I came across the Conventional Commits. Basically, they suggest a set of rules that makes it easier to keep track of commit history just by reading the subjects.

There are variations of these rules, that change according to the company. I gathered information about some similar suggested structures and wrote everything below, so I have a base I can start to work with.

Suggested structure
#

[type]([optional scope]): [description]
[blank line]
[optional body]
[blank line]
[optional footer]

Some rules
#

No line can be longer than 72 characters (some references say 80, 100… so it changes)
The first line must be in lowercase and without punctuation at the end (some say to use a capital letter, but mostly say not to)
Body and footer start with a capital letter
There must be a blank line between description and body and between body and footer
Write all in imperative, present tense, e.g., use fix, not fixed nor fixes
Be objective and don’t write something more than once, remember the body is optional

Type
#

A list of recommended types include:

BREAKING CHANGE or type!: A breaking API change. May be used in the type or as an entry in the footer. It can be used as part of commits of any type by using ! after the type name, e.g., feat!, fix!.
build: Changes that affect the build system or external dependencies.
chore: Changes that do not relate to a fix or feature and don’t modify scr or test files e.g. updating dependencies.
ci: Changes to continuous integration configuration files and scripts.
docs: Documentation changes such as the README or other markdown files.
feat: A new feature.
fix: A bug fix.
perf: A code change that improves performance.
refactor: A code change that neither fixes a bug nor adds a feature.
revert: Reverts a previous commit. The description must include the header of the reverted commit and the body/footer must contain its SHA.
style: Changes that don’t affect the meaning of the code, e.g., blankspaces, formatting, missing semi-colons.
test: Adding missing tests or correcting existing ones.

It should be all in lowercase (except for BREAKING CHANGE) and followed by : or (scope), without blankspaces. Feel free to use other types or to rename these, if it fits your project.

Scope
#

A noun describing a section of the codebase. Optional.

Description
#

A short summary of the code changes. In the imperative, present tense, without capitalized first letter and no punctuation at the end.

Body
#

Additional contextual information about the code changes, such as the changes made, the motivation and what was the original problem. Do not explain the implementation, but the background and reasoning. Must begin with one blank line after the description. It may consist of any number of newline separated paragraphs. Also in the imperative, present tense.

Footer
#

It changes from one reference to another. Conventional Commits say it must have word tokens with hyphen (-) instead of whitespaces characters followed by a string, e.g., “Reviewd-by: John Doe”, “Reference: #1234”. But I also read that it can be written as an closing reference to an issue, for example. It changes. Must begin with one blank line after the body.

That’s it. Let’s improve the readability of our commits.

Stay safe!