Git Hook Manager

Paul Ollivier contact@paulollivier.fr

This project is an attempt to provide a way to easily share git hooks.

In many teams, we rely on a full suite of tooling, and the need to share code conventions and quality standards.

This tool tries to unify git hook management via the well-known shared repository dotfiles mechanisms.

Installation

Grab yourself a copy from the latest release page, chmod +x it, and put it in one of the directories in your $PATH. May I recommend ~/.local/bin?

Or, if you have cargo: cargo install git-hooks-manager. In this case, the binary will be found in ~/.cargo/bin.

Usage

.git-hooks binary help page [source]

$ git-hooks --help
git-hooks
Paul Ollivier <contact@paulollivier.fr>
A git hooks manager

USAGE:
    git-hooks [SUBCOMMAND]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    help           Prints this message or the help of the given subcommand(s)
    init           Install the git hooks in .git/hooks
    run            Runs the configured hooks for a given event
    self-update    git-hooks will try to update itself.

If you are starting a new project, or at least trying git-hooks on a new project, you should run git-hooks init. This will setup the project to run git-hooks on git events.

If you want to run a hook collection manually, you can call git-hooks run <event>:

.Help text of git-hooks' "run" command [source,shell]

git-hooks-run
Runs the configured hooks for a given event

USAGE:
    git-hooks run <event>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

ARGS:
    <event>    Runs the hook for the given event, eg. "pre-commit", "post-commit"… [possible values: apply-patch-
               msg, commit-msg, post-commit, post-update, pre-apply-patch, pre-commit, pre-merge-commit,
               pre-push, pre-rebase, pre-receive, prepare-commit-msg, update]

Using & writing hooks

This is covered in link:hooks.adoc[it's own page].

Design doc

I am convinced Rust is the language to go regarding system tooling, for its performance and error handling design.

The solution has 3 parts:

• The config file inside a repository, specifying which hook to enable for everyone, as well as hook sources.
• Multiple hook repositories containing code to set up and use a variety of tools. For instance, a rust repository may contain the definitions of a rustfmt, cargo check, or even cargo test hook.
• The binary provided by the code alongside the document you are reading right now. This binary needs to handle reading the repos' config file, downloading the hook repositories, and apply them on the proper git events (pre-commit, post-commit, …)

The .hooks.yml file

This file is expected to be found at the root of the git repository. It contains definitions to be read by the main binary.

.Example file for a rust project [source,yaml]

repos:
  - https://github.com/paulollivier/rust-hooks
hooks:
  - name: cargofmt

A hook definitions repository

This is a simple git repository, with a hooks.yml at its root.

[WARN]

Not to be confused by the .hooks.yml! The dotted version is to use the git hook manager for the current repo, the non-dotted version is for hooks definitions!

.Sample file containing hook definition [source,yaml]

hooks:
  - name: rustfmt
    on_event:
      - pre-commit
    on_file_regex:
      - "*.rs"
    action: "rustfmt {files}"
    setup_script: rustfmt_setup.sh

.Sample repository structure [source]

.
|-- hooks.yml
`-- rustfmt_setup.sh

The git-hooks binary

Roles

• manage hook repos:
• clone hooks repos
• pull repos
• checkout a specific hook repo revision
• init the hook repos (execute their setup script)
• .hooks.yml hooks section overrides hooks.yml definition if set
• set itself up as to be executed on git events
• (partial impl.) handle multiple args arguments, such as {file}, {files}, {root}, {changed_files}
• restrict execution to specified file regexps
• run only when the git index contains the specified file regexps
• implement self-update