convcommitlint

CONVCOMMITLINT

A simple, slightly opinionated, but actually usable linter for Conventional Commits, written in Go.

Motivation

I just wanted something that works out of the box. No over-configuration, no headaches—just simple commit linting! This being said, this linter covers the essentials. Contributions are welcome, but I don’t intend to support every possible variation or custom rule!

Features

• Checks header syntax
• Detects common typos in key keywords: fix, feat, and BREAKING CHANGE
• GitHub Pull Request Reviews:
  • Request changes (default)
  • Comment-only mode
• Lint Modes:
  • Lint only the current commit
  • Lint all commits
  • Lint only recent commits from the base branch
• Full environment variable support for all flags
• Cross-platform: Linux, macOS, and Windows
• GitHub Action support

How It Works

convcommitlint checks your commits against the Conventional Commits standard.
If you use it as a GitHub Action or enable PR review, it will comment or request changes directly on your pull requests, listing any issues it finds.

Usage

  convcommitlint [flags]
  convcommitlint [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  version     Print convcommitlint version

Flags:
  -b, --base-branch string   The base branch to check commits from (default "main")
      --comment-only         Pull request reviews will only comment instead of requesting changes
  -r, --create-review        Creates review on github pull request
  -c, --current              Lint only the current commit
  -h, --help                 help for convcommitlint
  -a, --lint-all             Lint all repository commits
  -p, --path string          Git repository path (default "./")
      --pr-number int        The number of pull request to create the review
      --repository string    The github repository in owner/name format ex: coolapso/convcommitlint

Use "convcommitlint [command] --help" for more information about a command.

Environment Variables

Every flag can also be set with an environment variable, using the CONVCOMMITLINT_ prefix, uppercase, and underscores.
For example, the flag --lint-all becomes the variable CONVCOMMITLINT_LINT_ALL.

GitHub Action

You can use convcommitlint as part of your CI pipeline. Most CLI arguments are supported as action inputs.

convcommitlint:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: coolapso/convcommitlint@v0

Base Branch

By default, the base branch is "main". If you use a different default branch, set the base-branch input:

convcommitlint:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: coolapso/convcommitlint@v0
      with: 
        base-branch: develop

Git History Depth

By default, the action checks out the reference branch with full history. To limit this, use the fetch-depth input (commits beyond this depth will not be analyzed):

convcommitlint:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: coolapso/convcommitlint@v0
      with: 
        fetch-depth: 10

Disable Pull Request Reviews

PR reviews are enabled by default. To disable them, set create-review to "false":

convcommitlint:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: coolapso/convcommitlint@v0
      with: 
        create-review: "false"

Use a Specific Version

The action uses the latest release by default. To pin a specific version:

convcommitlint:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: coolapso/convcommitlint@v0
      with: 
        version: v0.2.0

Other Features & Flags

The action supports all CLI features and flags.
Check available inputs in action.yaml.
If an input is missing, you can always set the corresponding environment variable.

Installation

Docker

Images are available on both DockerHub and GitHub Container Registry (ghcr.io):

GitHub Container Registry:

docker run -v $(pwd):/data --rm ghcr.io/coolapso/convcommitlint:latest

DockerHub:

docker run -v $(pwd):/data --rm coolapso/convcommitlint:latest

Go Install

Latest Version

go install github.com/coolapso/convcommitlint@latest

Specific Version

go install github.com/coolapso/convcommitlint@v1.0.0

Arch Linux (AUR)

On Arch Linux, use the AUR package: convcommitlint-bin.

Linux Install Script

Install on any Linux distro using the script:

Latest Version

curl -L http://commitlint.coolapso.sh/install.sh | bash

Specific Version

curl -L http://commitlint.coolapso.sh/install.sh | VERSION="v1.1.0" bash

Manual Install

• Download the binary from the releases page
• Extract the binary
• Run it

Build

go build -o convcommitlint

Contributions

Improvements and suggestions are always welcome!
Check open issues, or open a new Issue or Pull Request.

If you like this project and want to support or contribute in another way, you can ❤ Sponsor Me or: