Dead-simple tool for enforcing clean commit messages.
Project description
mkcommit
mkcommit
is an extremely simple tool made for commit message generation.
Why?
Why would anybody need this? Aren't editors enough?
When working in teams it's hard to enforce proper Git commit message style from everyone. This CLI tool asks you questions to build a commit message that you can configure for yourself and your team with a very simple Python script.
commitlint
exists. Why mkcommit
?
commitlint
is a great tool. But it has considerable learning curve if you want to leverage its full potential. This tool strives to be the exact opposite: provide bare minimum with almost no overhead for your teammates. All they will need to learn is this one command: mkcommit
.
Installation
If you have Python set up, you're good to go. Run pip install mkcommit
and you're done.
Usage
- Run
mkcommit
to generate a Git commit message and print it to standard output. - Run
mkcommit -c
to generate a Git commmit message and copy it to your clipboard.
Configuration
-
At the root of your repository create a Python filed named
my_repo.mkcommit.py
. -
Compose the script:
from mkcommit import Keyword, CommitMessage, ask, to_stdout keywords = [ Keyword( "feat", "New feature" ), Keyword( "fix", "Bugfix" ), ] keyword = ask("Keyword", one_of=keywords) ticket_number = ask("Ticket number") first_line = ask("Short commit message") extended_message = ask("Long commit message") c = CommitMessage( f"[{ticket_number}] {keyword.keyword}: {first_line}", extended_message ) if __name__ == "__main__": to_stdout(c)
The above example shows a treasure-trove of configuration options:
Keyword
- can be used to create selection lists of keywordsask
- the main prompt function usingInquirerPy
at the back-end. It consists of the following modes:- Bare - e.g.
ask("blah")
asks for direct textual input. one_of
- asks the user to select one value from a list.one_or_more
- asks the user to select at least one value from a list.yes_no
- asks the user a yes/no question.
- Bare - e.g.
CommitMessage
- consists of two fields, the first one is the first-line commit message that will appear directly ingit log
and the second field is an extended commit message (usually optional).to_stdout(c)
at the very end specifies the default behavior when the script is ran directly instead of withmkcommit
. This is optional if you only intend to use themkcommit
command and do not wish to ever trigger the script directly.
-
Run
mkcommit
. You can either:- Run it as
mkcommit -f /path/to/some.mkcommit.py
- Or trigger it in the current working directory.
mkcommit
will search for all*.mkcommit.py
files and will let you select the one applicable from the list (this way you can have many config files for many diverse scenarios if you so forsee).
- Run it as
Input validation
Right now, we're offering the following options for input validation:
mkcommit.validators.is_int
- validates input as integersmkcommit.validators.is_float
- validates input as floating-point numbersmkcommit.validators.max_len
- raises a validation error if maximum length is exceededmkcommit.validators.matches
- matches an arbitrary regex pattern
Example of usage:
from mkcommit import Keyword, CommitMessage, ask
from mkcommit.validators import is_int, matches
ticket_number = ask("Ticket number", is_int()) # integer ticket number
initials = ask("Initials", matches(r'\w\w\w\w')) # 4-letter initials
Writing your own validators
It is possible to quickly write your own validators. You need to create a function with a signature that matches mkcommit.model.ValidatorClosure
, so a function that returns another function, where the inner function accepts a string and returns a boolean. Quick example:
from mkcommit.model import Validator
import re
def matches(pattern: str) -> Validator:
def _v(msg: str) -> bool:
if re.match(pattern, msg):
return True
else:
return False
return _v
The above is the implementation of the matches
validator.
You can declare validators directly within your *.mkcommit.py
file or import them from somewhere else.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.