Git hook scripts

A set of configurable git hooks and checks.

Upon committing code, the pre-commit hook runs configured checks against the files to be committed and rejects the commit if any of the checks turned on fail.

Install using pip:

pip install captainhook

You can then install the hooks using:

captainhook install

from within any git repo, and the pre-commit hook will be installed.

You can perform a run against all your code base using:

captainhook run

To turn a check on or off, create a tox.ini file in the base directory of your project with a captainhook section.

eg:

[captainhook]
flake8=off
pdb=off
python3=on
block_branch=on;master

flake8, pdb and python3 checks default to being on.

Checks can also be passed arguments from the config file. This is done with the following notation:

<check_name>=<status>;<string to be passed through>

Currently checks can only be passed a single argument and must do the parsing of that themselves.

flake8 obeys the configuration as per the flake8 docs but any path-related options will need to use wildcard patterns (e.g. exclude=*/migrations/* instead of exclude=migrations).

To avoid being checked at all, you can commit using the --no-verify flag:

git commit -a --no-verify

Currently supported checks are

• pdb: Checks to see if there are any uncommented import pdb; pdb.set_trace() statements in the code to be committed.
• flake8: Runs flake8 against the files that are set to be committed.
• python3: Checks to see if python files set to be committed are python3 compatible.
• isort: Checks to see if all import statements have been sorted correctly.
• grep: Runs the given grep command against the files in your commit.
  • Takes a single argument; options which will be passed through to grep verbatim.
  • Currently you can only specify a single grep command.
• block_branch: Checks if the current branch is in a list of branches that should not be committed to.
• merge_marks: Checks if there are any signs of unresolved merge marks in the files to be committed.

You only see output for checks that fail, otherwise silence.

Example output upon a rejected commit:

===============================================================================
Checking python3
===============================================================================
--- captainhook/pre_commit.py   (original)
+++ captainhook/pre_commit.py   (refactored)
@@ -66,7 +66,7 @@
     "Check there are changes to stash"
     return bool(bash('git diff'))

-print 'a'
+print('a')
===============================================================================
Checking flake8
===============================================================================
pre-commit.py:19:1: F401 'importlib' imported but unused
pre-commit.py:128:1: E302 expected 2 blank lines, found 1
setup.py:25:80: E501 line too long (89 > 79 characters)
===============================================================================
Rejecting commit
===============================================================================

You can add your own check to your git env quite easily.

Simply add a module to .git/hooks/checkers with a run() method defined.

The method should return the error string on faillure, or a False like object on success.

For example:

$ cat .git/hooks/checkers/mine.py
DEFAULT = 'on'
def run():
    return "NOT A CHANCE"

This will block all commits if enabled.

A checker can set the following variables:

DEFAULT: used to determine the check is assumed "on" or "off". This value is only used if tox.ini has not been used to override it. The default DEFAULT is off.

CHECK_NAME: To override the display name of the module.

REQUIRED_FILES: Files that, if present, should be included in the copy to the temp directoy before analysis takes place.

I'm interested in hearing feedback - positive or negative - about this.

Please make yourself at home, create issues if you've got problems with existing behaviour, or suggestions for future improvements or anything else.

You can reach me on twitter @couperalex.

Running pre-commit.py on its own will by default create copies of the files to be committed which you probably don't want when testing a new check.

You can run the script against all your code base using:

python captainhook/pre_commit.py --all