Document the helper functions

README.md

@@ -50,6 +50,29 @@ If you use Nix with flakes, you can simply add it to your program's devshell ins
      )
 ```
 
+## What do you put in your commit messages?
+
+Simply add a bash script enclosed in a `git-check-assertions` block to a commit message, e.g.:
+
+~~~
+```git-check-assertions
+dotnet build
+dotnet test --no-build
+```
+~~~
+
+This script will be run with `set -euo pipefail`, and the commit will be considered correct if the script exits succesfully.
+
+You can technically assert that a command fails by writing `! ... || exit 1`, or write assertions about a command's output by piping it to `grep`, but doing so won't lead to very useful error messages when things go wrong. To make those things easier, there are some helper functions included, which are inspired by [bats](https://github.com/bats-core/bats-core) and [bats-assert](https://github.com/bats-core/bats-assert):
+
+* `run <command>`: run a command, capturing its exit status in `status` and combined stdout/stderr in `output`.
+* `assert_success`: succeed if `run` produced a zero exit status.
+* `assert_failure`: succeed if `run` produced a non-zero exit status.
+* `assert_output <string>`: succeed if `output` exactly matches the string.
+* `assert_output --partial <string>`: succeed if `output` contains the string.
+
+I'm considering taking `bats-assert` as a dependency, but for now, this very minimal set of functions with a similar interface should get you on your way.
+
 ## Examples of commit messages
 
 Assert that a commit builds:
@@ -65,7 +88,8 @@ Assert that a commit builds and that the tests succeed:
 ~~~
 ```git-check-assertions
 dotnet build
-dotnet test --no-build
+run dotnet test --no-build
+assert_success
 ```
 ~~~