precommit-message-perservation

This is a simple library that makes it easier to code hooks for pre-commit that validate commit messages that preserve the commit message on failure. In other words, if the user writes a long commit message and your pre-commit hook tells them the message is bad, they won't have their message entirely thrown away.

For users

You need to make sure that you include this hook in your list of hooks that prepare commit messages, ideally the first entry. This allows the hook to populate your editor with previously saved commit messages. You can install the hook by adding something like this to your .pre-commit-config.yaml file:

...
repos:
-   repo: https://github.com/EliRibble/precommit-message-preservation.git
    rev: 1.0
    hooks:
    -   id: precommit-message-preservation
        stages: [prepare-commit-msg]
...

Any pre-commit hook that uses this library when analyzing commit messages will dump rejected commit messages into the SQLite database at $XDG_CACHE_HOME/precommit-message-preservation.db. The precommit-message-preservation hook will then pull out these commit messages when the repository and branch match and populate your editor with the saved message.

For developers

If you are working on a pre-commit hook that analyzes (and rejects) commit messages then you can use this library to improve your user experience. Normally when pre-commit hooks fail on commit-msg the contents of the commit message are thrown away. Instead you can use this library to save the messages for your users. To use it follow these three simple steps

Step 1: Add dependency

Depending on your packaging software you'll edit something like setup.py or setup.cfg and add a dependency on this library.

Step 2: Initialize your argument parser

import argparse

import precommit_message_preservation

def main():
	parser = argparse.ArgumentParser()
	precommit_message_preservation.add_arguments(parser)

You need to create an ArgumentParser and let precommit-message-preservation populate it with some standard arguments. These are used internally in the next step.

Step 3: Analyze the commit

args = parser.parse_args()
try:
	with precommit_message_preservation.GetAndPreserveMessage(args, hookname="my hook") as message:
		# do analysis on 'message'
except:
	print("your message is inadequate because X, Y, and Z")
	sys.exit()

precommit-message-preservation expects to know whether or not it should keep the message based on whether or not an exception was emitted within the GetAndPreserveMessage context manager. This context manager extracts the commit message using the arguments provided in args and gives the cleaned message back to the calling code. The message will not have any code diffs or comments in it. The context manager immediately saves the message in the database. If it exits cleanly it deletes the message. Otherwise the message is saved and will be provided back to the user on the next commit attempt.

Hacking

You'll want to install the developer dependencies:

pip install -e .[develop]

This will include nose2, which is the test runner of choice. After you make modifications you can run tests with

nose2

When you're satisfied you'll want to update the version number and do build-and-upload:

python setup.py sdist bdist_wheel
twine upload dist/* --verbose