From b9d55f8f29e426270c7591603c61750262f68881 Mon Sep 17 00:00:00 2001
From: Simon Ruderich <simon@ruderich.org>
Date: Thu, 26 Feb 2026 06:43:50 +0100
Subject: [PATCH] README: document post-commit mode

---
 README.adoc | 33 ++++++++++++++++++++++++++++-----
 1 file changed, 28 insertions(+), 5 deletions(-)

diff --git a/README.adoc b/README.adoc
index 357c11c..ee56ef0 100644
--- a/README.adoc
+++ b/README.adoc
@@ -1,10 +1,11 @@
 = README
 
 punyci is a smaller than tiny continuous integration (CI) tool for Git and
-Podman. It runs as post-receive hook and executes the jobs with Podman in the
-background. If a job fails it sends a mail to the current user. The container
-is kept alive for an hour to debug issues "live" without needing multiple
-runs.
+Podman. It runs as post-receive or post-commit hook and executes the jobs with
+Podman in the background. If a job fails it sends a mail to the current user.
+The container is kept alive for an hour to debug issues "live" without needing
+multiple runs. To debug issues with punyci the job can also be run in the
+foreground.
 
 punyci is free software and licensed under GPL version 3 or later.
 
@@ -16,13 +17,15 @@ Compile `punyci` with `go build` or `make`.
 Setup `podman` for an unprivileged user. To receive mails `/usr/bin/sendmail`
 needs to be installed (provided by e.g. Postfix, nullmailer, etc.). Create a
 bare Git repository and call `punyci post-receive` from the post-receive hook.
+Alternatively, setup a regular Git repository and call `punyci post-commit`
+from the post-commit hook.
 
 punyci can run on the same host or on a remote host via SSH.
 
 
 == Usage
 
-Example:
+Example (post-receive):
 
     $ git init --bare repo.git
     $ echo 'punyci post-receive' > repo.git/hooks/post-receive
@@ -62,6 +65,26 @@ To run the CI in the foreground use `git push -o wait`. This needs the option
 the command will hang until the timeout. Simply press Ctrl-C or kill the
 containers manually.
 
+Example (post-commit):
+
+    $ git init repo
+    $ echo 'punyci post-commit' > repo/.git/hooks/post-commit
+    $ chmod +x repo/.git/hooks/post-commit
+
+    $ cd repo
+    $ cat > .punyci.toml <<EOF
+    [[Jobs]]
+    Image = "debian:trixie"
+    Script = "exit 1"
+    EOF
+    $ git add .punyci.toml
+    $ git commit -m punyci
+    2026/02/26 06:41:15 punyci: queued 1 jobs
+    [...]
+
+The behavior is the same as above. To run the CI in the foreground use
+`PUNYCI=wait git commit`.
+
 
 == Configuration
 
-- 
2.52.0