From 0b669acac07a2b325316a46cca01a5cb85eede3b Mon Sep 17 00:00:00 2001
From: Owen Jacobson <owen@grimoire.ca>
Date: Wed, 17 Jun 2020 17:39:07 -0400
Subject: Provide a git hook to automate tests.

When enabled, these hooks run the same tests as Travis, every commit.
There's nothing inherently wrong with a failing test run (it's a useful
signal), but the turnaround time for responding to Travis is a lot
longer than the turnaround time for responding to a local test failure.

The tradeoff here is that `git commit`, which is a _very_ common
operation, takes considerably longer when the hooks are enabled, and
runs a higher risk of giving users doorway effect issues.
---
 README.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 9cffd6d..ff7ce8f 100644
--- a/README.md
+++ b/README.md
@@ -38,3 +38,44 @@ the page as a suggestion.
 
 Stable links provide the user with an index into this list. When you insert new
 items, insert them at the end.
+
+## Git hooks
+
+This project includes a pre-commit and a pre-merge-commit hook to run tests.
+Using this hook is optional, but it'll catch a lot of minor breakage before
+Travis does.
+
+**Security note**: Enabling in-repository hooks means that anyone who can commit
+code to this repository can run that code on your computer. Only do this if
+you're willing to take that chance.
+
+To set this up:
+
+* Install additional Rust components:
+
+    ```bash
+    rustup component add clippy rustfmt
+    ```
+
+* Install `cargo-udeps`:
+
+    ```bash
+    cargo install cargo-udeps
+    ```
+
+* Configure Git to use these hooks:
+
+    ```bash
+    git config core.hooksPath .git-hooks
+    ```
+
+This only needs to be done once, and applies only to this project. To undo this,
+unset `core.hooksPath`:
+
+```bash
+git config --unset core.hooksPath
+```
+
+You can also temporarily suppress the hook with `git commit --no-verify`, if you
+have broken code you want to check in, or if the internet is unavailable for
+Cargo to download dependencies.
-- 
cgit v1.2.3