skip to navigation
skip to content

captainhook 0.8.2

A collection of git commit hooks

Latest Version: 0.8.6


Git hook scripts

What is it

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

Once installed into your environment, you will be able to run::


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

Setting Up

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



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


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

- grep: Runs the given grep command against the files in your commit.
- Takes a single argument; options which will be passed through to grep
- Currently you can only specify a single grep command.


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

Example output upon a rejected commit::

Checking python3
File "captainhook/", line 77
print 'a'
SyntaxError: invalid syntax
Checking flake8
=============================================================================== F401 'importlib' imported but unused E302 expected 2 blank lines, found 1 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/
def run():
return "NOT A CHANCE"

This will block all commits if enabled.

A variable ``DEFAULT`` can be specified in the module and will be 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.


I'm eager to get some 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 on its own will by default cause a ``git stash`` to take
place which you probably don't want when testing a new check.

You can run the script without performing such a stash using::

python captainhook/ -n  
File Type Py Version Uploaded on Size
captainhook-0.8.2.tar.gz (md5) Source 2014-05-31 9KB
  • Downloads (All Versions):
  • 3 downloads in the last day
  • 189 downloads in the last week
  • 1079 downloads in the last month