Conventional Commits Linter

Pre 1.0.0 breaking changes may be introduced without increasing the major version.

A tooling and language agnostic utility to lint Git commits against the Conventional Commits specification.

Why use Conventional Commits Linter?

• No Dependencies - A binary download is provided, removing dependencies on downloading tools or interpreter languages.
• Correctness - The linting against the Conventional Commits specification is strict. Numerous violations missed by other linters are caught.
• Sensible Defaults - By default no subjective linting rules are applied, only compliance with the Conventional Commits specification is asserted.
• Configurable - While by default no subjective linting rules are applied, additional subjective linting rules can be enabled.
• Fast - Utilising Rust the performance is significantly better than other interpreted language linters.

• Usage
• Examples
  • GitHub Actions
  • GitLab CI
• Installation
  • Binary
  • Cargo
  • Docker

Usage

Conventional Commits Linter can either operate upon a range of Git commits in the repositories' history or on a commit message from standard in. To provide a commit message by standard in use - as the positional argument and standard in will be read. Otherwise to specify the range of commits you can provide a commit hash or reference as a positional argument. The range of commits starts exclusively from the commit specified till inclusively of HEAD.

All commit messages provided or within the range are linted against the Conventional Commits v1.0.0 specification. If any commits messages fail linting then an error message explaining why is logged and Conventional Commits Linter exits with a non zero exit code.

The only required argument is a commit hash/reference as a positional argument, or - to read from standard input.

Examples

GitHub Actions

name: Conventional Commits

on: pull_request

permissions:
  contents: read

jobs:
  linting:
    name: Linting
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/developerc286/conventional_commits_linter:0.16.1
    steps:
      - name: Checkout code.
        uses: actions/checkout@v5
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
      - name: Check Conventional Commits linting.
        run: conventional_commits_linter --type angular "origin/${{ github.base_ref }}"

GitLab CI

conventional-commits-linting:
    stage: conventional-commits-linting
    image: rust
    before_script:
        - version="v0.16.1" && wget -O - "https://github.com/DeveloperC286/conventional_commits_linter/releases/download/${version}/x86_64-unknown-linux-musl.tar.gz" | tar xz --directory "/usr/bin/"
    script:
        # Lint all the commits in the branch.
        - conventional_commits_linter --type angular "origin/${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME}"
    rules:
        - if: $CI_MERGE_REQUEST_ID

Installation

Binary

Statically linked compiled binaries are available for download. Visit the releases page at https://github.com/DeveloperC286/conventional_commits_linter/releases to see all the releases, the release notes contains links to binary downloads for various architectures.

If you do not trust the provided binaries another option is to compile your own and then make it available for remote download, so your CICD etc can then download it.

version="v0.16.1" && wget -O - "https://github.com/DeveloperC286/conventional_commits_linter/releases/download/${version}/x86_64-unknown-linux-musl.tar.gz" | tar xz --directory "/usr/bin/"

Cargo

Cargo is the Rust package manager, the install sub-command pulls from crates.io and then compiles the binary locally, placing the compiled binary at ${HOME}/.cargo/bin/conventional_commits_linter.

cargo install conventional_commits_linter

By default it installs the latest version at the time of execution. You can specify a specific version to install using the --version argument. For certain environments such as CICD etc you may want to pin the version.

e.g.

cargo install conventional_commits_linter --version 0.16.1

See https://doc.rust-lang.org/cargo/commands/cargo-install.html#install-options for more detailed documentation.

Docker

You can use the Docker image published to ghcr.io/developerc286/conventional_commits_linter.

docker run --rm -v $(pwd):/workspace -w /workspace ghcr.io/developerc286/conventional_commits_linter:latest origin/HEAD

Issues/Feature Requests

Report issues or request features on our GitHub Issues.