conventional-pre-commit

A pre-commit hook to check commit messages for Conventional Commits formatting.

Usage

Make sure pre-commit is installed.

Create a blank configuration file at the root of your repo, if needed:

touch .pre-commit-config.yaml

Add a new repo entry to your configuration file:

repos:
  # - repo: ...

  - repo: https://github.com/compilerla/conventional-pre-commit
    rev: <git sha or tag>
    hooks:
      - id: conventional-pre-commit
        stages: [commit-msg]
        args: [] # optional: list of Conventional Commits types to allow e.g. [feat, fix, ci, chore, test]

Install the pre-commit script:

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

Make a (normal) commit ❌:

$ git commit -m "add a new feature"

[INFO] Initializing environment for ....
Conventional Commit......................................................Failed
- hook id: conventional-pre-commit
- duration: 0.07s
- exit code: 1

[Bad Commit message] >> add a new feature

Your commit message does not follow Conventional Commits formatting
https://www.conventionalcommits.org/

Conventional Commits start with one of the below types, followed by a colon,
followed by the commit message:

    build chore ci docs feat fix perf refactor revert style test

Example commit message adding a feature:

    feat: implement new API

Example commit message fixing an issue:

    fix: remove infinite loop

Optionally, include a scope in parentheses after the type for more context:

    fix(account): remove infinite loop

Make a (conventional) commit ✔️:

$ git commit -m "feat: add a new feature"

[INFO] Initializing environment for ....
Conventional Commit......................................................Passed
- hook id: conventional-pre-commit
- duration: 0.05s

Install with pip

conventional-pre-commit can also be installed and used from the command line:

pip install conventional-pre-commit

Then run the command line script:

conventional-pre-commit [types] input

• [types] is an optional list of Conventional Commit types to allow (e.g. feat fix chore)

• input is a file containing the commit message to check:

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

Or from a Python program:

from conventional_pre_commit.format import is_conventional

# prints True
print(is_conventional("feat: this is a conventional commit"))

# prints False
print(is_conventional("nope: this is not a conventional commit"))

# prints True
print(is_conventional("custom: this is a conventional commit", types=["custom"]))

Development

conventional-pre-commit comes with a VS Code devcontainer configuration to provide a consistent development environment.

With the Remote - Containers extension enabled, open the folder containing this repository inside Visual Studio Code.

You should receive a prompt in the Visual Studio Code window; click Reopen in Container to run the development environment inside the devcontainer.

If you do not receive a prompt, or when you feel like starting from a fresh environment:

1. Ctrl/Cmd+Shift+P to bring up the command palette in Visual Studio Code
2. Type Remote-Containers to filter the commands
3. Select Rebuild and Reopen in Container to completely rebuild the devcontainer
4. Select Reopen in Container to reopen the most recent devcontainer build

Versioning

Versioning generally follows Semantic Versioning.

Making a release

Releases to PyPI are triggered by publishing a release on GitHub.

1. Create a branch chore/release

2. Bump the version in pyproject.toml

3. PR, merge chore/release into main

4. Tag main with the new version (prefixed by v):

   git fetch
   git reset --hard origin/main
   git tag vX.Y.Z
   git push origin vX.Y.Z

5. Publish a pre-release to push the new package to TestPyPI

6. Publish a regular Release to push the new package to PyPI

License

Apache 2.0

Inspired by matthorgan's pre-commit-conventional-commits.