Hooky: Plugin based git hooks

Tired of modifying hooks within your repository to do one or more things? Tired of making the same change across project repositories?

Hooky allows you to apply the logic from multiple hook plugins using git’s configuration.

For instance, consider if you have some repositories in which you want a branch name and description included in each commit. Business decisions require a file changelog in every commit, but only in a handful of repositories. Suppose you already have a prepare-commit-msg hook and commit-msg hook in those repositories. You’d need to decide which of these hooks to modify, and you now have hooks with differing logic across repositories.

With hooky, you may configure multiple repositories with the branch-detail and taskboard plugins, and in only the few repositories which require file changes in the commit message you may enable the changes plugin.

Setup

Clone this repository to a shared location. ~/.config/hooky is the recommended location. For other options, see git-init template directory.

Important

Always manually inspect the scripts in script-executing frameworks such as hooky before applying them.

mkdir ~/.config
git clone https://github.com/jimschubert/hooky.git ~/.config/hooky

Then, configure git to use hooky as your git template directory:

git config --global init.templatedir '~/.config/hooky/git/'

Usage

Add one of the supported plugins to the hooky.plugins config key. This is a multi-valued key.

For example, add json-validator and changes:

git config --add hooky.plugins json-validator
git config --add hooky.plugins changes

Remove a plugin individually:

git config --unset hooky.plugins changes

Or uninstall hooky from a repo completely:

git config --unset-all hooky.plugins

Plugins

branch-detail

Print out the branch name and its description (if present) to each commit message.

Configs

• branch.BRANCH_NAME.description

  • Common git configuration option, allows you to configure a description for a git branch. To set, git branch --edit-description.

changes

One of git’s built-in examples, this appends diff details to the commit message (uncommented).

json-validator

Verifies that any .json file being added or modified represents a valid JSON syntax. By default, this passes each modified JSON file through python -M json.tool.

Options

Key	Description	Default
hooky.json-validator.command	Defines the json common to invoke. Individual JSON files are passed as an argument following this command.	python -m json.tool
hooky.json-validator.defer-empty	Whether or not we all the command defined above to decide if a completely empty JSON file is valid. If set to false, an empty file is considered invalid JSON, which matches behavior of the default command, python -m json.tool and the JSON specification.	false

taskboard

Evaluates a branch name for common taskboard patterns, and appends a link to the taskboard location in a commit message.

Options

Key	Description	Default
hooky.taskboard.prefix	Defines the prefix used to determine if a branch is in a taskboard format. Evaluation becomes the format prefix-digits.	N/A
hooky.taskboard.urltemplate	Provides the non-digit part of a URL to your branch’s related task item.	N/A
hooky.taskboard.separator	Defines the separator used between the board prefix and digits, e.g. prefix-digits or prefix/digits.	-
hooky.taskboard.once	Constrain the appended URL to occurring only once, up to the branch point. By default, appends on every commit.	false

Contributing

Testing

Tests are written with bats. Please follow bats-core installation instructions before running tests.

Extending

Hooky can be used as a starter point for your plugin infrastructure a well. Just clone this repo, and add your plugins under git/hooks/plugins/PLUGIN_NAME. A plugin may have one or more git hooks defined; create the hook (e.g. prepare-commit-msg, commit-msg, or both), and make sure these hooks are executable.

Hooky will traverse all plugins defined in the git config element hooky.plugins, and execute these according to which top-level hook has invoked the hooky function (see git/hooks/pre-commit, for instance). If hooky doesn’t include the top-level hook, just add it and invoke the hooky function. For example, to enable pre-push hooks in your fork, in git/hooks/pre-push, add this minimal script:

#!/usr/bin/env bash
. "$(git --exec-path)/git-sh-setup"
. "$GIT_DIR/hooks/hooky.sh"
hooky "pre-push" "$@"

Ensure that the new pre-push file is executable. Now, git will invoke pre-push and your pre-push hook will invoke hooky, which in turn invokes all pre-push hooks for any enabled plugin which defines it.

License

Apache 2.0