Format of Git commit message and conventional commit

In the daily work of developers, submitting code to Git is an essential action. How to write the message when the code is submitted? The most basic principle is: if the team has a commit format requirement, follow that requirement. This is the same as coding style. The format of the commit message is not absolutely good or bad, the most important thing is to maintain consistency.

If the team does not have specific formatting requirements, here are some suggestions.

Messages should be split into two parts, subject and content, separated by a blank line. The subject part briefly describes the content of the commit, and should not be too long; the content part should specifically describe the modification made and the reason for the modification.

Regarding the format of commit messages, there is a popular specification called conventional commit. Conventional submission makes some conventions on the submission information, which is convenient for automated tools to process.

Conventional commits use the following format:

<类型>[可选 范围]: <描述>

[可选 正文]

[可选 脚注]

A conventional submission consists of 3 parts, namely type and description , body and footnotes , where the body and footnotes are optional.

The first part is type and description. Type is the classification of the commit. The commonly used types are as follows:

• fix Indicates a bug fix.

• feat Indicates new features.

• build Indicates build-related.

• chore Represents repetitive day-to-day tasks, such as updating the version of a dependency.

• ci Indicates continuous integration related.

• docs Indicates that the document is related.

• style Indicates that the code format is relevant.

• refactor Indicates code refactoring.

• perf Indicates performance-related.

• test Indicates test-related.

An optional range can be added after the type, placed in brackets, indicating the component corresponding to the commit. For example, fix(api) to indicate a bug fix to an API component.

The second part of the message is the optional body, which can use spaces to separate multiple paragraphs.

The third part of the message is an optional footer. The footnote adopts the git trailer format, which is a simple name-value pair.

An example commit message is given below, from Angular's GitHub repository.

feat(docs-infra): add @developerPreview tag for APIs in developer preview (#46050)

This commit adds a tag processor for `@developerPreview`. Adding this tag to
an exported symbol or to a decorator parameter causes an API status tag to
be shown for the API which links to the Developer Preview documentation.

PR Close #46050

Conventional commits have special handling for breaking changes. If the commit changes contain destructive changes, there are two ways to express:

• The first way is to add an exclamation mark after the type and range, eg  feat(api)!.

• The second way is to add in a footnote  BREAKING CHANGE, eg  BREAKING CHANGE: some changes.

BREAKING CHANGE An example commit in use is given below  .

fix(router): Remove deprecated initialNavigation option (#45729)
BREAKING CHANGE:
`initialNavigation: 'enabled'` was deprecated in v11 and is replaced by
`initialNavigation: 'enabledBlocking'`.

PR Close #45729

If you want to see what a fully formatted commit looks like, you can refer to the source code repository of Linux and Git. For example, the commit below is from Git.

sha1-file.c: don't freshen cruft packs
We don't bother to freshen objects stored in a cruft pack individually
by updating the `.mtimes` file. This is because we can't portably `mmap`
and write into the middle of a file (i.e., to update the mtime of just
one object). Instead, we would have to rewrite the entire `.mtimes` file
which may incur some wasted effort especially if there a lot of cruft
objects and they are freshened infrequently.

Instead, force the freshening code to avoid an optimizing write by
writing out the object loose and letting it pick up a current mtime.

This works because we prefer the mtime of the loose copy of an object
when both a loose and packed one exist (whether or not the packed copy
comes from a cruft pack or not).

This could certainly do with a test and/or be included earlier in this
series/PR, but I want to wait until after I have a chance to clean up
the overly-repetitive nature of the cruft pack tests in general.

Signed-off-by: Taylor Blau <[email protected]>
Signed-off-by: Junio C Hamano <[email protected]>

For the video corresponding to the article, see my B station and video number.