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
      • Config Precedence
      • Message Precedence
    • hook
    • debug
  • Default Config
    • Commit Types
  • Ignore Patterns
    • Default Ignore Patterns
    • Custom Ignore Patterns
    • Disabling Default Ignores
  • Available Rules
    • Length rules
    • Enum / allow-list rules
    • Charset rules
    • Case rules
    • Empty / presence rules
    • Full-stop rules
    • Leading-blank rules
    • Header formatting rules
    • Trailer / sign-off rules
    • Breaking change rules
  • Available Formatters
  • Programmatic Usage
    • One-liner with default config
    • Full control with default config
    • Lint with a config file
    • Custom rules
    • Custom formatters
  • 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

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 "

Rules marked ✅ enabled are active by default. All others can be opted into via the rules: list in your config.

All case rules accept one of: lower-case, upper-case, camel-case, kebab-case, pascal-case, sentence-case, snake-case, start-case.

These rules enforce that a field is not empty.

Check that a field does not end with a given character (default ".").

Enforce that a blank line separates commit sections (conventional commits spec).

The argument is the trailer token. A trailing : is accepted and stripped automatically, so "Signed-off-by" and "Signed-off-by:" are equivalent.

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

All public packages are importable. The module path is github.com/conventionalcommit/commitlint.

go get github.com/conventionalcommit/commitlint@latest

Key packages:

The simplest entry point — no config file required:

package main

import (
    "fmt"
    "github.com/conventionalcommit/commitlint/config"
)

func main() {
    result, err := config.LintMessage("feat: add login page")
    if err != nil {
        panic(err)
    }

    for _, issue := range result.Issues() {
        fmt.Printf("%s: %s: %s\n", issue.Severity(), issue.RuleName(), issue.Description())
    }

    if len(result.Issues()) == 0 {
        fmt.Println("commit message is valid")
    }
}

Build the linter yourself for more control (e.g. to swap the formatter):

package main

import (
    "fmt"
    "github.com/conventionalcommit/commitlint/config"
    "github.com/conventionalcommit/commitlint/formatter"
)

func main() {
    conf := config.NewDefault()
    // optionally customise conf here

    linter, err := config.NewLinter(conf)
    if err != nil {
        panic(err)
    }

    result, err := linter.ParseAndLint("feat: add login page")
    if err != nil {
        panic(err)
    }

    out, err := (&formatter.JSONFormatter{}).Format(result)
    if err != nil {
        panic(err)
    }
    fmt.Println(out)
}

Load a .commitlint.yaml and lint against it:

package main

import (
    "fmt"
    "github.com/conventionalcommit/commitlint/config"
)

func main() {
    conf, err := config.Parse(".commitlint.yaml")
    if err != nil {
        panic(err)
    }

    linter, err := config.NewLinter(conf)
    if err != nil {
        panic(err)
    }

    result, err := linter.ParseAndLint("feat: add login page")
    if err != nil {
        panic(err)
    }

    for _, issue := range result.Issues() {
        fmt.Printf("%s: %s\n", issue.RuleName(), issue.Description())
    }
}

Implement the lint.Rule interface and register it before building a linter:

package main

import (
    "fmt"
    "github.com/conventionalcommit/commitlint/config"
    "github.com/conventionalcommit/commitlint/lint"
    "github.com/conventionalcommit/commitlint/registry"
)

// NoWIPRule rejects commit messages whose description starts with "WIP".
type NoWIPRule struct{}

func (r *NoWIPRule) Name() string { return "no-wip" }
func (r *NoWIPRule) Apply(setting lint.RuleSetting) error { return nil }
func (r *NoWIPRule) Validate(commit lint.Commit) (*lint.Issue, error) {
    if len(commit.Description()) >= 3 && commit.Description()[:3] == "WIP" {
        return lint.NewIssue("description must not start with WIP"), nil
    }
    return nil, nil
}

func main() {
    if err := registry.RegisterRule(&NoWIPRule{}); err != nil {
        panic(err)
    }

    conf := config.NewDefault()
    conf.Rules = append(conf.Rules, "no-wip")
    conf.Settings["no-wip"] = lint.RuleSetting{}

    linter, err := config.NewLinter(conf)
    if err != nil {
        panic(err)
    }

    result, err := linter.ParseAndLint("feat: WIP do not merge")
    if err != nil {
        panic(err)
    }

    for _, issue := range result.Issues() {
        fmt.Printf("%s: %s\n", issue.RuleName(), issue.Description())
    }
}

Implement lint.Formatter and register it:

package main

import (
    "fmt"
    "strings"
    "github.com/conventionalcommit/commitlint/config"
    "github.com/conventionalcommit/commitlint/lint"
    "github.com/conventionalcommit/commitlint/registry"
)

type SimpleFormatter struct{}

func (f *SimpleFormatter) Name() string { return "simple" }
func (f *SimpleFormatter) Format(result *lint.Result) (string, error) {
    if len(result.Issues()) == 0 {
        return "ok", nil
    }
    var sb strings.Builder
    for _, issue := range result.Issues() {
        fmt.Fprintf(&sb, "[%s] %s: %s\n", issue.Severity(), issue.RuleName(), issue.Description())
    }
    return sb.String(), nil
}

func main() {
    if err := registry.RegisterFormatter(&SimpleFormatter{}); err != nil {
        panic(err)
    }

    conf := config.NewDefault()
    conf.Formatter = "simple"

    format, err := config.GetFormatter(conf)
    if err != nil {
        panic(err)
    }

    linter, err := config.NewLinter(conf)
    if err != nil {
        panic(err)
    }

    result, err := linter.ParseAndLint("bad message")
    if err != nil {
        panic(err)
    }

    out, err := format.Format(result)
    if err != nil {
        panic(err)
    }
    fmt.Print(out)
}

• 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