Become a Pro at Commit Messages using Commitlint

5 min readOct 23, 2023

As a developer, I’ve often found myself uncertain about what to include in a commit message, a challenge I’m sure many developers can relate to.

When hundreds of individuals work on the same project, they will all have different ideas for creating commit messages. It will soon throw your commits into chaos. Fortunately, there is a lint that will require developers to adhere to the same formatting guidelines.

A well-written code with a lousy commit message is like a beautifully baked cake with no frosting.

The commitlint adheres to specific formatting guidelines to avoid chaos and provides a universal structure that everyone can easily read.

Commitlint

Commitlint maintains consistent formatting and style for commit messages in version control systems like Git. It helps ensure that developers follow a specific set of rules or conventions when writing commit messages, making it easier to manage and maintain a project’s commit history and generate changelogs.

Commitlint is often used in conjunction with other tools and libraries, such as Husky and Lint-staged, to perform checks on commit messages before they are approved and committed to the repository. This guarantees that all commits follow a set standard or format, such as recommendations for the structure, length, and content of commit messages.

Commit Structure

The commit message should be structured as follows:

type(scope?): subject #scope is optional; multiple scopes are supported (current delimiter options: “/”, “\” and “,”)
body?
footer?

A commit that has the text BREAKING CHANGE: at the beginning of its optional body or footer section introduces a breaking API change.

The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history, which makes it easier to write automated tools on top of it. This convention corresponds with SemVer, by describing the features, fixes, and breaking changes made in commit messages.

//Real-World Example
chore: run tests on travis ci

Commits Elements

type

A prefix for the commit message describing the type of change. The type is a noun. The following are the different types:

build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
ci: Changes to CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
chore: Changes which doesn't change source code or tests, e.g. changes to the build process, auxiliary tools, and libraries
docs: Documentation only changes
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: Revert something
style: Changes that do not affect the meaning of the code (white space, formatting, missing semi-colons, etc)
test: Adding missing tests or correcting existing tests

Examples

build: update npm dependency

ci: add circleci configuration file

docs: fix typo in foo.md and bar.md

perf: optimize database query for faster response times

feat: allow provided config object to extend other configs

fix: resolve issue with incorrect data rendering

refactor: reorganize code structure for better readability

style: format code according to Prettier standards

test: add unit tests for user authentication

Check these pages to see the officially allowed types.

Type section on the Angular repo. This is linked from the Conventional Commits website as “Angular Convention”. It explains what build etc. means.
Allowed types defined in the docs of the config-conventional section of the commitlint repo. This presumably works closely or exactly with the Angular standard.

2. scope

The standard defines the use of an optional scope, which is used in addition to the required type.

An optional scope MAY be provided after a type.

A scope is a phrase describing a section of the codebase enclosed in parenthesis.

e.g. ‘fix(parser):’ This would be specific to a particular project, so you cannot know the general scopes for all projects. The standard says you should agree with your team on what the scope would be. Perhaps based on features, projects or directories.

Examples using scope:

build(deps): upgrade packages

style(deps): remove whitespace in requirements.txt

feat(lang): add Polish language

Commit message with multi-paragraph body and multiple footers

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123

Specification

1. Commits MUST be prefixed with a type, which consists of a verb, feat, fix, etc., followed by a colon and a space.

2. The type feat MUST be used when a commit adds a new feature to your application or library.

3. The type fix MUST be used when a commit represents a bug fix for your application.

4. An optional scope MAY be provided after a type. A scope is a phrase describing a section of the codebase enclosed in parenthesis, e.g., fix(parser):

5. A description MUST immediately follow the type/scope prefix. The description is a short description of the pull request, e.g.,

fix: array parsing issue when multiple spaces were contained in string.

6. A longer commit body MAY be provided after the short description. The body MUST begin with one blank line after the description.

7. A footer MAY be provided with one blank line after the body. The footer SHOULD contain additional meta-information about the pull-request (such as the issues it fixes, e.g., fixes #13, #5 ).

8. Breaking changes MUST be indicated at the very beginning of the footer or body section of a commit. A breaking change MUST consist of the uppercase text BREAKING CHANGE, followed by a colon and a space.

9. A description MUST be provided after the BREAKING CHANGE: describing what has changed about the API, e.g., BREAKING CHANGE: environment variables now take precedence over config files.

10. Types other than feat and fix MAY be used in your commit messages.

The upcoming article will focus on the custom commitlint and its integration.