comlipy by slashplus - lint commit messages with python

Demo generated with svg-term-cli

comlipy is a helper that makes it incredibly easy to check whether your commit messages follow predefined or custom commit message standards or not.

This means that after setting up comlipy in combination with a custom git commit-msg hook (further information), comlipy takes care of the provided commit msg and warns you whenever a message does not fit your style.

By default comlipy follows the conventional commit standards, but you can easily change the configuration in order to fit your needs.

Requirements

• python 3.7+
• pip (pip3) or brew
• poetry

Installation

Installation with brew (recommended)

# Add the source
brew tap slashplus/comlipy git@gitlab.com:slashplus-build/comlipy.git

# Install comlipy
brew install comlipy

Installation with pip

pip3 install comlipy

Development installation

Install the repository by git cloning it and by setting up a virtual environment using poetry:

git clone git@gitlab.com:slashplus-build/comlipy.git # clone repo
cd comlipy/ # change to comlipy directory
poetry install # install dependencies

Run comlipy:

poetry shell # open the virtual environment

# or just run a single command
# poetry run comlipy-install

Usage

Setting up a git commit-msg hook (optional)

Comlipy comes with a simple git commit-msg hook installer. This sets up a commit-msg hook that checks the commit message before the actual commit. An example commit-msg hook can be found here

Make sure you have initialized git in your project. And then just run comlipy-install, or comlipy-install -c 'PATH/TO/CUSTOM/CONFIGFILE.yml' if you want to set a default config override.

Note: Don't worry, the installer will not automatically override an existing commit-msg hook. In case such file already exists, you will be asked if you want to override it.

Tip: Sometimes it can be useful to to set up a custom git hooks path, instead of overriding the commit-msg hook directly. Learn more about it here.

Setting up a a custom configuration override (optional)

Its on you to configure comlipy so it perfectly fits your needs by setting up and passing a custom configuration yml file. By doing this, you can override the default configuration i.e. enable or disable rules or changing the message behaviour (none, warning, error).

See docs for further details.

Documentation

Documentation is currently not finished. Following a list of available references:

• docs: ALL documents
• rules: Reference of all available validation rules with configuration values
• ignores: Reference of default validation ignores and how to add custom ignores
• commit-msg sample hook: Example git commit-msg hook
• cli: List of available cli flags

Configuration

It is possible to change the configuration values. This way you are able to change rule behaviour of all rules by providing values for applicable, value, level or you can change global settings i.e. the help message.

Therefore you must define a custom YAML file with the rules to override and pass the custom config file path via parameter:

If a config rule is not set, the default value will be used instead.

Example config-comlipy.yml

## global definitions
global:
  help: 'get help here: foo-bar-baz.abc'

rules:
  header-min-length:
    applicable: 'always'
    value: 0
    level: 1
  header-max-length: 
    applicable: 'always'
    value: 123
    level: 2
  scope-case:
    value: 'upper-case'
  scope-empty:
    applicable: 'never'
    level: 2
ignores:
    - '^SKIPME' #skip validations where header starts with "SKIPME"

Tests

You can run unit.tests by following the python 3 unittest documentation. For example:

python -m unittest comlipy.tests.lib.test_ensure
python -m unittest comlipy.tests.lib.test_rule_checker

or run all tests in batch:

# optionally run it in verbose mode (-v)
python -m unittest -v comlipy.tests.suite

Credits & inspiration

• commitlint
• conventional commit standards