conventional-pre-commit

To use conventional-pre-commit to automatically validate your commit messages during the git commit process, follow these steps:

1. Ensure pre-commit is installed on your system.
2. Create a .pre-commit-config.yaml file at your repository root if it doesn't exist.
3. Configure the default_install_hook_types to include commit-msg.
4. Add the conventional-pre-commit repository to your repos list.
5. Install the hooks using pre-commit install --install-hooks.

Note: When used as a hook, the input file argument is automatically supplied by pre-commit using the current commit's message file.

default_install_hook_types:
  - pre-commit
  - commit-msg

repos:
  - repo: https://github.com/compilerla/conventional-pre-commit
    rev: <git sha or tag>
    hooks:
      - id: conventional-pre-commit
        stages: [commit-msg]
        args: []

You can customize the validation rules for ConventionalCommit by providing specific types and scopes during initialization.

• Types: If you provide a list of types, they will be used for validation. Note that feat and fix are automatically included if they are present in the provided list or if the list is empty (using DEFAULT_TYPES).
• Scopes: If scopes are provided, the regex will strictly match only those scopes. If scopes is empty, it allows any word character or specific delimiters within the parentheses.

from conventional_pre_commit.format import ConventionalCommit

# Only allow 'docs' type and 'api' scope
cc = ConventionalCommit(
    commit_msg="docs(api): update readme",
    types=["docs"],
    scope_optional=False,
    scopes=["api"]
)
print(cc.is_valid())  # True

The following options are available for the conventional-pre-commit command line interface:

usage: conventional-pre-commit [-h] [--no-color] [--force-scope] [--scopes SCOPES] [--strict] [--verbose] [types ...] input

Check a git commit message for Conventional Commits formatting.

positional arguments:
  types            Optional list of types to support
  input            A file containing a git commit message

options:
  -h, --help       show this help message and exit
  --no-color       Disable color in output.
  --force-scope    Force commit to have scope defined.
  --scopes SCOPES  List of scopes to support. Scopes should be separated by commas with no spaces (e.g. api,client).
  --strict         Force commit to strictly follow Conventional Commits formatting. Disallows fixup! and merge commits.
  --verbose        Print more verbose error output.

You can install conventional-pre-commit via pip and run it directly from the command line to check a specific commit message file.

Installation:

pip install conventional-pre-commit

Usage:

conventional-pre-commit [types] input

• [types]: An optional list of allowed Conventional Commit types (e.g., feat fix chore).
• input: The path to the file containing the commit message to check.

Example:

conventional-pre-commit feat fix chore ci test .git/COMMIT_MSG

The verbose_arg function returns a formatted string suggesting that the user use the --verbose argument to obtain more detailed information about errors.

from conventional_pre_commit.output import verbose_arg
print(verbose_arg(use_color=True))

The unicode_decode_error function returns a formatted error message used when the tool fails to decode a commit message. It suggests that the user ensure Git is configured to write commit messages in UTF-8 encoding.

from conventional_pre_commit.output import unicode_decode_error
error_msg = unicode_decode_error(use_color=True)

For a quick boolean check without instantiating a class, use the is_conventional convenience function.

is_conventional(input, types=None, optional_scope=True, scopes=[]) -> bool

from conventional_pre_commit.format import is_conventional

# Simple check
valid = is_conventional("feat: something")

# Custom types and required scope
valid_custom = is_conventional(
    "custom: something", 
    types=["custom"], 
    optional_scope=False
)

The Commit class provides base functionality for inspecting and cleaning git commit messages. It can identify autosquash prefixes (like fixup! or squash!) and detect if a commit is a merge commit.

Key methods:

• clean(commit_msg): Removes comments (lines starting with #) and ignored verbose commit segments from the message.
• has_autosquash_prefix(commit_msg): Returns True if the cleaned message starts with a git autosquash prefix (e.g., fixup! ).
• is_merge(commit_msg): Returns True if the message indicates a merge (e.g., starts with Merge ).

from conventional_pre_commit.format import Commit

commit = Commit("fixup! feat: new feature")
print(commit.has_autosquash_prefix())  # True

merge_commit = Commit("Merge branch 'main'")
print(merge_commit.is_merge())  # True

The fail function generates a formatted error string when a commit message does not adhere to the Conventional Commits specification. It includes the offending message, a warning, and a link to the specification. You can control whether ANSI color codes are included using the use_color parameter.

from conventional_pre_commit.output import fail
# Assuming a ConventionalCommit object 'commit' exists
error_message = fail(commit, use_color=True)