precommit-message-preservation 1.3
A library for preserving and restoring commit messages
Requires Python: >=3.6

# precommit-message-perservation

This is a simple library that makes it easier to code hooks for [pre-commit](https://pre-commit.com) 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:

```yaml
...
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
```