Metadata-Version: 2.1
Name: precommit-message-preservation
Version: 1.3
Summary: A library for preserving and restoring commit messages
Home-page: https://github.com/EliRibble/precommit-message-preservation
Author: Eli Ribble
Author-email: eliribble@google.com
License: UNKNOWN
Description: # 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
        ```
        
Platform: UNKNOWN
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Provides-Extra: develop
