commitlint is a tool designed to lint your commit messages according to the Conventional Commits standard for your pre-commit hook and GitHub Actions.

A conventional commit message follows a specific format that includes a prefix indicating the type of change, an optional scope for context, and a concise description of the modification. This structure improves readability, facilitates automated changelog generation, and ensures a consistent commit history.

The commit message should follow this structure:

<type>(<optional scope>): <description>

[Optional body]

Type: Indicates the type of change, such as build, ci, docs, feat, fix, perf, refactor, style, test, chore, revert, or bump. E.g., feat: add JSON parser.

Scope: Additional contextual information. E.g., feat(parser): add JSON parser.

Description: Brief description of the commit.

Body: A detailed description of the commit.

For more details, please refer to the Conventional Commits specification at https://www.conventionalcommits.org/en/v1.0.0/

NOTE: commitlint also checks the length of the commit header (max 72 characters). The commit header refers to the first line of the commit message (excluding the body).

1. Add the following configuration on .pre-commit-config.yaml.

   repos:
      ...
      - repo: https://github.com/opensource-nepal/commitlint
        rev: v1.0.0
        hooks:
          - id: commitlint
      ...

2. Install the commit-msg hook in your project repo:

   pre-commit install --hook-type commit-msg

NOTE: Installing using only pre-commit install will not work.

If you have any existing workflows, add the following steps:

...
steps:
    ...
    - name: Run commitlint
      uses: opensource-nepal/commitlint@v1
    ...

If you don't have any workflows, create a new GitHub workflow, e.g. .github/workflows/commitlint.yaml.

name: Commitlint

on:
  push:
    branches: ['main']
  pull_request:

jobs:
  commitlint:
    runs-on: ubuntu-latest
    name: Commitlint
    steps:
      - name: Run commitlint
        uses: opensource-nepal/commitlint@v1

NOTE: commitlint GitHub Actions will only be triggered by "push", "pull_request", or "pull_request_target" events. The difference between "pull_request" and "pull_request_target" is that "pull_request" is more secure for public repos while "pull_request_target" is necessary for private repos.

pip install commitlint

commitlint [-h] [-V] [--file FILE] [--hash HASH] [--from-hash FROM_HASH] [--to-hash TO_HASH] [--skip-detail] [-q | -v]
           [commit_message]

positional arguments:
  commit_message        The commit message to be checked

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  --file FILE           Path to a file containing the commit message
  --hash HASH           Commit hash
  --from-hash FROM_HASH
                        From commit hash
  --to-hash TO_HASH     To commit hash
  --skip-detail         Skip the detailed error message check
  -q, --quiet           Ignore stdout and stderr
  -v, --verbose         Verbose output

Check commit message directly:

$ commitlint "chore: my commit message"

Check commit message from file:

$ commitlint --file /foo/bar/commit-message.txt

Check commit message of a hash:

$ commitlint --hash 9a8c08173

Check commit message of a hash range:

$ commitlint --from-hash 00bf73fef7 --to-hash d6301f1eb0

Check commit message skipping the detail check:

$ commitlint --skip-detail "chore: my commit message"
# or
$ commitlint --skip-detail --hash 9a8c08173

Run commitlint in quiet mode:

$ commitlint --quiet "chore: my commit message"

Run commitlint in verbose mode:

$ commitlint --verbose "chore: my commit message"

Version check:

$ commitlint --version
# or
$ commitlint -V

We appreciate feedback and contribution to this package. To get started please see our contribution guide.