quickhook

Quickhook is a fast, Unix'y, opinionated Git hook runner. It handles running all user-defined hooks, collecting their output, reporting failures, and exiting with a non-zero status code if appropriate.

Installation

If you're on Mac there is a Homebrew tap for Quickhook:

brew tap dirk/quickhook
# Tapped 1 formula (28 files, 28KB).

brew install quickhook
# /usr/local/Cellar/quickhook/1.4.0: 3 files, 3.7MB, built in 9 seconds

Usage

First you'll need to set Quickhook to be called in your Git hooks. The quickhook install command will discover hooks defined in the .quickhook directory and create Git hook shims for those. For example, the below is what you can expect if you clone this repository and install the shims:

$ quickhook install
Create file .git/hooks/commit-msg? [yn] y
Installed shim .git/hooks/commit-msg
Create file .git/hooks/pre-commit? [yn] y
Installed shim .git/hooks/pre-commit

To make it easier to test hooks outside of the normal Git paths the hook sub-commands provide some additional options. For example, these are some of the options you can use with the pre-commit hook command:

# Run the pre-commit hooks on all Git-tracked files in the repository
quickhook hook pre-commit --all

# Run them on just one or more files
quickhook hook pre-commit --files hooks/commit_msg.go hooks/pre_commit.go

You can see all of the options by passing --help to the sub-command:

$ quickhook hook pre-commit --help
...
OPTIONS:
   --all, -a    Run on all Git-tracked files
   --files, -F  Run on the given comma-separated list of files

Writing hooks

Quickhook will look for hooks in a corresponding sub-directory of the .quickhook directory in your repository. For example, it will look for pre-commit hooks in .quickhook/pre-commit/. A hook is any executable file in that directory. See the go-vet file for an example.

pre-commit

Pre-commit hooks receive the list of staged files separated by newlines on stdin. They are expected to write their result to stdout/stderr (Quickhook doesn't care). If they exit with a non-zero exit code then the commit will be aborted and their output displayed to the user.

Note: Pre-commit hooks will be executed in parallel and should not mutate the local repository state.

File-and-line-specific errors should be written in the following format:

some/directory/and/file.go:123: Something doesn't look right

A more formal definition of an error line is:

• Sequence of characters representing a valid path
• A colon (:) character
• Integer of the line where the error occurred
• A color character followed by a space character
• Any printable character describing the error
• A newline (\n) terminating the error line

This informal Unix convention is already followed by many programming languages, linters, and so forth.

commit-msg

Commit-message hooks are run sequentially. They receive a single argument: a path to a temporary file containing the message for the commit. If they exit with a non-zero exit code the commit will be aborted and any stdout/stderr output displayed to the user.

Given that they are run sequentially, commit-msg hooks are allowed to mutate the commit message temporary file.

Performance

Quickhook is designed to be as fast and lightweight as possible. There are a few guiding principles for this:

• Ship as a small, self-contained executable.
• Eschew configuration in favor of rigid adherence to Unix'y approach of composing programs.
• Do as much as possible in parallel.

License

Released under the Modified BSD license, see LICENSE for details.