commitlint pre-commit hooks

pre-commit hooks for commitlint

Using commitlint with pre-commit

Derivation

Add this to your .pre-commit-config.yaml:

- repo: https://github.com/aentwist/pre-commit-mirrors-commitlint
  rev: ""  # Use the sha / tag you want to point at
  hooks:
    - id: commitlint

Since this is a commit-msg hook (not a typical, pre-commit hook), it needs additional configuration. By default, pre-commit runs hooks in all stages but only installs one stage, pre-commit. Adding a commit-msg hook we also need to install the commit-msg stage, but then since hooks are run in all stages by default, other hooks in the file will run multiple times. To prevent this, we can flip this logic: run hooks in specific stages and install hooks for all stages (or just the stages we need).

# Install hooks for all stages instead of just for the pre-commit stage.
default_install_hook_types: [pre-commit, commit-msg]
# Limit hooks to running in the pre-commit stage unless specified otherwise.
default_stages: [pre-commit]
repos:
  - repo: https://github.com/aentwist/pre-commit-mirrors-commitlint
    rev: ""  # Use the sha / tag you want to point at
    hooks:
      - id: commitlint
        # commitlint is a commit-msg hook
        stages: [commit-msg]

See Configuring hooks to run at certain stages.

Finally, when using plugins with commitlint you'll need to declare them under additional_dependencies. Since this overrides the additional_dependencies in this hook, you will also need to redeclare the commitlint dependency. For example:

- repo: https://github.com/aentwist/pre-commit-mirrors-commitlint
  rev: v18.2.0
  hooks:
    - id: commitlint
      additional_dependencies:
        - commitlint@18.2.0
        - "@commitlint/config-conventional@18.1.0"

Combining these ideas together, we have a complete example:

Result

default_install_hook_types: [pre-commit, commit-msg]
default_stages: [pre-commit]
repos:
  - repo: https://github.com/aentwist/pre-commit-mirrors-commitlint
    rev: v18.2.0
    hooks:
      - id: commitlint
        stages: [commit-msg]
        additional_dependencies:
          - commitlint@18.2.0
          - "@commitlint/config-conventional@18.1.0"

CI

The main hook checks a commit message at the time it is made. To run on a range of commits after they have been made, we need a separate hook.

This hook is commitlint-all. It runs commitlint on all commits. Note that it cannot run only on branch commits due to pre-commit limitations. To explore other options see the discussion.

Derivation

Adding the commitlint-all hook, we have

default_install_hook_types: [pre-commit, commit-msg]
default_stages: [pre-commit]
repos:
  - repo: https://github.com/aentwist/pre-commit-mirrors-commitlint
    rev: v18.2.0
    hooks:
      - id: commitlint
        stages: [commit-msg]
        additional_dependencies:
          - commitlint@18.2.0
          - "@commitlint/config-conventional@18.1.0"
      - id: commitlint-all
        stages: [manual]
        additional_dependencies:
          - commitlint@18.2.0
          - "@commitlint/config-conventional@18.1.0"

We can DRY this out with a YAML anchor:

Result

default_install_hook_types: [pre-commit, commit-msg]
default_stages: [pre-commit]
repos:
  - repo: https://github.com/aentwist/pre-commit-mirrors-commitlint
    rev: v18.2.0
    hooks:
      - id: commitlint
        stages: [commit-msg]
        additional_dependencies: &commitlint-additional-dependencies
          - commitlint@18.2.0
          - "@commitlint/config-conventional@18.1.0"
      - id: commitlint-all
        stages: [manual]
        additional_dependencies: *commitlint-additional-dependencies

Run the hook manually with pre-commit run --hook-stage=manual --files .pre-commit-config.yaml commitlint-all.

Note that we need to both specify the hook stage, and feed pre-commit some files so it knows it needs to run the hook. Using --all-files runs the hook once per file; instead, specify only one file to run the hook once. Choose the one file we know exists: the pre-commit config.