Configuration

Configuration

Configuration files

Configuration files are simple Python scripts that should be named:

• either *.mkcommit.py, where * is any Python-compliant name
• or .mkcommit.py (recommended when you inted to use a single file per repo)

You can place those files:

• either at the root of the repository - all matching files will be globbed and displayed as a selectable list
• or in an .mkcommit subfolder - if .mkcommit folder exists, it will be the only folder to be searched and all matching files will be displayed in a selectable list.

Default patterns

A built-in semantic commit suite can be used:

from mkcommit import CommitMessage, to_stdout
from mkcommit.suites import semantic

def commit():
    return CommitMessage(semantic.default_short(), semantic.default_long())

def on_commit(msg: CommitMessage):
    semantic.is_semantic(msg.first_line)
    semantic.has_short_commit_msg_proper_length(msg.first_line)

if __name__ == "__main__":
    to_stdout(commit())

Put this at the root of your repo or in any of the supported locations.

Custom configuration

If you need to define your own keywords and commit message template you can use mkcommit's building blocks:

from mkcommit import Keyword, CommitMessage, ask, to_stdout

keywords = [
    Keyword(
        "feat",
        "New feature"
    ),
    Keyword(
        "fix",
        "Bugfix"
    ),
]

def commit():
    keyword = ask("Keyword", one_of=keywords)
    ticket_number = ask("Ticket number")
    first_line = ask("Short commit message")
    extended_message = ask("Long commit message")

    return CommitMessage(
        f"[{ticket_number}] {keyword.keyword}: {first_line}",
        extended_message
    )

if __name__ == "__main__":
    to_stdout(commit()))

The above example shows a treasure-trove of configuration options:

• Keyword - can be used to create selection lists of keywords
• commit - wraps the creation of a CommitMessage into a function. This is more useful than direct creation of the CommitMessage object, since we can make the interactive less eager in contexts that don't require the interactive session, e.g. creating a mkcommit-based Git Hook
• ask - the main prompt function using InquirerPy 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.
• CommitMessage - consists of two fields, the first one is the first-line commit message that will appear directly in git log and the second field is an extended commit message (usually optional).
• to_stdout(commit()) at the very end specifies the default behavior when the script is ran directly instead of with mkcommit. This is optional if you only intend to use the mkcommit command and do not wish to ever trigger the script directly.

How it works

mkcommit has several runtime modes:

• Default - for mkcommit. Runs the retrieved commit() function from the *.mkcommit.py file which will spawn the interactive questions used to assemble a commit message and then runs git commit -m with the produced commit message as the argument.
• STDOUT - for mkcommit -s. As default, but instead of running git commit -m it just prints the assembled commit message.
• Clipboard - for mkcommit -c. As default, but instead of running git commit -m it just copies the assembled commit message to the clipboard.
• STDOUT + Clipboard - for mkcommit -s -c. It prints and copies the commit message at the same time.
• Hook - for mkcommit -x "some commit msg". Validates "some commit msg" by finding the on_commit(msg) function in the *.mkcommit.py file. This mode should be used when on_commit(msg) is implemented in your *.mkcommit.py file and used with an externally fed commit message. Using this mode does not trigger the interactive commit() procedure.

Hence the *.mkcommit.py file to be valid should contain:

• commit() function definition that returns a CommitMessage instance.
• on_commit(msg) (optional) function definition if hook mode will be used. This function should accept a CommitMessage instance as an argument.