commitlint

commitlint checks if your commit message meets the conventional commit format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

• Why Use Conventional Commits?

Table of Contents

• commitlint
  • Table of Contents
  • Installation
    • Releases
    • Using go
  • Setup
    • Manual
  • Quick Test
  • Commands
    • config
    • lint
      • Precedence
        • Config
        • Message
    • hook
    • debug
  • Default Config
    • Commit Types
  • Available Rules
  • Available Formatters
  • Extensibility
  • FAQ
  • License

Installation

Releases

Download binary from releases and add it to your PATH

Using go

go install github.com/conventionalcommit/commitlint@latest

Setup

• Enable for a single git repository, cd to repository directory

commitlint init

• Enable globally for all git repositories

commitlint init --global

• to customize hooks destination pass --hookspath with desired location

commitlint init --hookspath /path/to/hooks
commitlint init --global --hookspath /path/to/hooks

Manual

• run commitlint hook create to create .commitlint/hooks containing git hooks
  • pass --hookspath to customize the hooks output path
• To enable in single repo
  • run git config core.hooksPath /path/to/.commitlint/hooks
• To enable globally
  • run git config --global core.hooksPath /path/to/.commitlint/hooks

Quick Test

• Valid commit message

echo "feat: good commit message" | commitlint lint
# ✔ commit message

• Invalid commit message

echo "fear: do not fear for commit message" | commitlint lint
#   ❌ type-enum: type 'fear' is not allowed, you can use one of [build chore ci docs feat fix merge perf refactor revert style test]

Commands

config

• To create config file, run commitlint config create this will create commitlint.yaml

• To validate config file, run commitlint config check --config=/path/to/conf.yaml

lint

To lint a message, you can use any one of the following

• run commitlint lint --message=file
• run echo "message" | commitlint lint
• run commitlint lint < file

Precedence

commitlint lint follows below order for config and message

Config

• config file passed to --config command-line argument
• COMMITLINT_CONFIG env variable
• config file in current directory or git repo root in the below order
  • .commitlint.yml
  • .commitlint.yaml
  • commitlint.yml
  • commitlint.yaml
• default config

Message

• stdin pipe stream
• commit message file passed to --message command-line argument
• .git/COMMIT_EDITMSG in current directory

hook

• To create hook files, run commitlint hook create

debug

To prints useful information for debugging commitlint

run commitlint debug

Default Config

version: v0.9.0
formatter: default
rules:
- header-min-length
- header-max-length
- body-max-line-length
- footer-max-line-length
- type-enum
severity:
  default: error
settings:
  body-max-line-length:
    argument: 72
  footer-max-line-length:
    argument: 72
  header-min-length:
    argument: 10
  header-max-length:
    argument: 50
  type-enum:
    argument:
    - feat
    - fix
    - docs
    - style
    - refactor
    - perf
    - test
    - build
    - ci
    - chore
    - revert

Commit Types

Commonly used commit types from Conventional Commit Types

Type	Description
feat	A new feature
fix	A bug fix
docs	Documentation only changes
style	Changes that do not affect the meaning of the code (white-space, formatting etc)
refactor	A code change that neither fixes a bug nor adds a feature
perf	A code change that improves performance
test	Adding missing tests or correcting existing tests
build	Changes that affect the build system or external dependencies
ci	Changes to our CI configuration files and scripts
chore	Other changes that don't modify src or test files
revert	Reverts a previous commit

Available Rules

The list of available lint rules

name	argument	flags	description
header-min-length	int	n/a	checks the min length of header (first line)
header-max-length	int	n/a	checks the max length of header (first line)
body-max-line-length	int	n/a	checks the max length of each line in body
footer-max-line-length	int	n/a	checks the max length of each line in footer
type-enum	[]string	n/a	restrict type to given list of string
scope-enum	[]string	allow-empty: bool	restrict scope to given list of string
footer-enum	[]string	n/a	restrict footer token to given list of string
type-min-length	int	n/a	checks the min length of type
type-max-length	int	n/a	checks the max length of type
scope-min-length	int	n/a	checks the min length of scope
scope-max-length	int	n/a	checks the max length of scope
description-min-length	int	n/a	checks the min length of description
description-max-length	int	n/a	checks the max length of description
body-min-length	int	n/a	checks the min length of body
body-max-length	int	n/a	checks the max length of body
footer-min-length	int	n/a	checks the min length of footer
footer-max-length	int	n/a	checks the max length of footer
type-charset	string	n/a	restricts type to given charset
scope-charset	string	n/a	restricts scope to given charset
footer-type-enum	[]{token, types, values}	n/a	enforces footer notes for given type

Available Formatters

• default

commitlint

→ input: "fear: do not fear for ..."

Errors:
  ❌ type-enum: type 'fear' is not allowed, you can use one of [build chore ci docs feat fix perf refactor revert style test]

Total 1 errors, 0 warnings, 0 other severities

• JSON

{"input":"fear: do not fear for commit message","issues":[{"description":"type 'fear' is not allowed, you can use one of [build chore ci docs feat fix perf refactor revert style test]","name":"type-enum","severity":"error"}]}

Extensibility

FAQ

• How to have custom config for each repository?

  Place .commitlint.yaml file in repo root directory. linter follows config precedence.

  To create a sample config, run commitlint config create

• How can I skip lint check for a commit?

  use --no-verify flag with git commit which skips commit hooks

License

All packages are licensed under MIT License