# Git Hooks

The behavior of `git` commands can be customized through the use of "hooks".
These hooks are described in detail in git's
[documentation](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks).

`git` looks for an executables by name in the directory specified by
the `core.hooksPath` `git config` setting. The script `setup.py` here points
`core.hooksPath` at this directory. It runs during a `gclient sync` or a
`gclient runhooks`.

The hooks here are implemented in Dart by the program with
entrypoint `bin/main.dart` in this directory. The commands of the program
are the implementation of the different hooks, for example
`bin/main.dart pre-push ...`. Since the Dart program itself isn't an executable,
these commands are invoked by small Python wrapper scripts. These wrapper
scripts have the names that `git` will look for.

## pre-push

This hooks runs when pushing commits to a remote branch, for example to
create or update a pull request: `git push origin my-local-branch`.

The `pre-push` hook runs `ci/lint.sh` and `ci/format.sh`. `ci/analyze.sh` and
`ci/licenses.sh` are more expensive and are not run.

### Adding new pre-push checks

Since the pre-push checks run on every `git push`, they should run quickly.
New checks can be added by modifying the `run()` method of the `PrePushCommand`
class in `lib/src/pre_push_command.dart`.

## Creating a new hook

1. Check the `git` documentation, and copy `pre-push` into a script with
the right name.
1. Make sure the script has the executable bit set
(`chmod +x <script>`).
1. Add a new `Command` implementation under `lib/src`. Give the new
`Command` the same name as the new hook.
1. Add the new `Command` to the `CommandRunner` in `lib/githooks.dart`.
1. Make sure the script from step (1) is passing the new command to the Dart
program.