= Git Hook Manager
Paul Ollivier <contact@paulollivier.fr>

This project is an attempt to provide a way to easily share https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks[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 https://github.com/paulollivier/git-hooks/releases/latest[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:
** [x] clone hooks repos
** [x] pull repos
** [x] checkout a specific hook repo revision
* [x] init the hook repos (execute their setup script)
* [x] `.hooks.yml` hooks section overrides `hooks.yml` definition if set
* [x] set itself up as to be executed on git events
** [x] (partial impl.) handle multiple args arguments, such as `{file}`, `{files}`, `{root}`, `{changed_files}`
** [x] restrict execution to specified file regexps
** [x] run only when the git index contains the specified file regexps
* [x] implement self-update