commitlint checks if your commit message meets the conventional commit format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

• Why Use Conventional Commits?

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

Download binary from releases and add it to your PATH

go install github.com/conventionalcommit/commitlint@latest

• 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

• run commitlint hook to create .commitlint/hooks containing git hooks
  • pass --hookspath or -p 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

• To remove hooks from a single repository

commitlint remove

• To remove hooks globally

commitlint remove --global

Both commands ask for confirmation before unsetting core.hooksPath in git config. Hook files are left intact.

• 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]

• To create a config file, run commitlint config create, this will create .commitlint.yaml with only the enabled rules and their settings (compact format)

• To create a config file with all rules and settings written out (including disabled ones), run commitlint config create --all

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

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

commitlint lint follows below order for config and message

• 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

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

• To create hook files, run commitlint hook
  • pass --hookspath or -p to customize the hooks output directory
  • pass --replace or -r to overwrite existing hook files

To prints useful information for debugging commitlint

run commitlint debug

min-version: v0.11.0
formatter: default
rules:
- header-min-length
- header-max-length
- body-max-line-length
- footer-max-line-length
- type-enum
severity:
  default: error
  rules: {}
settings:
  body-max-line-length:
    argument: 100
    flags: {}
  footer-max-line-length:
    argument: 100
    flags: {}
  header-max-length:
    argument: 72
    flags: {}
  header-min-length:
    argument: 10
    flags: {}
  type-enum:
    argument:
    - feat
    - fix
    - docs
    - style
    - refactor
    - perf
    - test
    - build
    - ci
    - chore
    - revert
    flags: {}
disable-default-ignores: false
ignores: []

Commonly used commit types from Conventional Commit Types

commitlint automatically skips linting for commit messages generated by git (merges, reverts, fixups, etc.). If the first line of a commit message matches any ignore pattern, linting is skipped entirely.

The following patterns are enabled by default (source: config/default.go):

Add your own patterns in the config file under ignores:. User-defined patterns are additive, they are checked alongside the built-in defaults.

ignores:
  - "^WIP "
  - "^TICKET-\\d+"

If you want only your custom patterns (no built-in defaults), set disable-default-ignores: true:

disable-default-ignores: true
ignores:
  - "^WIP "

The list of available lint rules

• 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"}]}

• 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 (or commitlint config create --all to include all available settings)

• How can I skip lint check for a commit?

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

• How does commitlint handle merge / revert commits?

  commitlint ships with built-in ignore patterns that automatically skip linting for merge commits, reverts, fixups, squashes, and other git-generated messages. You can add your own patterns with the ignores config key, or disable the defaults with disable-default-ignores: true.

• Can I use the old version config key?

  Yes. The version key is still accepted for backward compatibility, but new config files should use min-version instead.

All packages are licensed under MIT License