Therapist Documentation¶

Overview / Installation¶

Therapist is a tool to help create robust, easily-configurable pre-commit hooks for Git. This allows you to find and fix common issues before you actually commit code to your repo.

Requirements¶

Python 2.7 or newer
Git

Installing Therapist¶

Installing Therapist is easily done using pip. Assuming it is installed just run the following from the command line:

$ pip install therapist

This command will download the latest version of Therapist from the Python Package Index and install it to your system. More information about pip and pypi can be found here:

Alternatively you can install from the distribution using the setup.py script:

$ python setup.py install

You could also install the development version by running the following:

$ pip install therapist==dev

Or simple install from a clone of the git repo:

$ git clone https://github.com/rehandalal/therapist.git
$ mkvirtualenv therapist
$ pip install -r requirements.txt
$ pip install --editable .

Quickstart¶

The first thing you should do is to install the git pre-commit hook. You can do this by running:

$ therapist install

Now all you need to do is create a configuration as outlined in the Configuration section.

Uninstallation¶

If you decide you no longer want to use the Therapist pre-commit hook, simply run:

$ therapist uninstall

Note

This will remove any pre-commit hook that is installed. It does not check to verify that it is the Therapist pre-commit hook.

Configuration¶

The configuration file¶

Once you have the Therapist pre-commit hook installed you will need to configure the actions that will be run before each commit. This is done with a .therapist.yml configuration file.

Add a file called .therapist.yml to the root directory of your project. The configuration file describes a set of actions like so:

actions:
    flake8:
        run: flake8 {files}
        include: "*.py"
        exclude:
            - "docs\*.py"
            - "migrations\*.py"
    eslint:
        description: ESLint
        run: yarn eslint {files}
        fix: yarn eslint --fix {files}
        include:
            - "*.js"
            - "*.jsx"
shortcuts:
    lint-all:
        flags:
            - use-tracked-files
            - include-untracked
    flake8-all:
        extends: lint-all
        options:
            action: flake8

Action definitions¶

There are several optional parameters that you can specify for a action. They are:

run:	This is the actual command to be run. You may use the named placeholder `{files}` which be replaced with a space-separated list of files that were modified and added to the commit.
fix:	This is the command to be run when the `--fix` option is used. You may use the named placeholder `{files}` which be replaced with a space-separated list of files that were modified and added to the commit.
description:	A short description of the command that is used to identify the command in the output. If it is longer than 68 characters, it will be truncated. If no description is provided it will default to the name of the command.
include:	This can be a single string or list strings of UNIX filename patterns. Files that match any of the patterns will be passed through to the command through `{files}` unless they match a pattern in the exclude parameter.
exclude:	This can be a single string or a list of strings of UNIX filename patterns. Files that match any of the patterns will never be passed through to the command through `{files}`.

Shortcut definitions¶

There are several optional parameters that you can specify for a shortcut. They are:

extends:	This is the name of another shortcut to extend.
options:	An associative array of options and their values to be passed to the `run` command.
flags:	A string or list of flags to be passed to the `run` command.

Command-Line Interface¶

Therapist comes with a basic command line tool therapist which can be used to install or uninstall the hook as well as run actions as a batch or individually.

Commands¶

For a list of commands simply run:

$ therapist --help

To get more information on a specific command run:

$ therapist <command-name> --help