Update forge docsHEADmaster

1 files changed, 40 insertions, 0 deletions

diff --git a/content/forge/internals/hookc.md b/content/forge/internals/hookc.md
new file mode 100644
index 0000000..3c270fc
--- /dev/null
+++ b/content/forge/internals/hookc.md
@@ -0,0 +1,40 @@
+---
+title: hookc
+---
+
+`hookc` is a helper binary for Git server-side hooks that relays the hook's
+context to a persistent daemon via a UNIX domain socket and communicates back
+any relevant responses.
+
+It is intended to be invoked by `git-receive-pack` for hooks such as
+`pre-receive`, `update`, and `post-receive`.
+
+## Environment variables
+
+- `LINDENII_FORGE_HOOKS_SOCKET_PATH`:
+  Absolute path to the UNIX domain socket on which the daemon is listening.
+- `LINDENII_FORGE_HOOKS_COOKIE`:
+  64-character authentication cookie used to validate the hook client to the
+  daemon.
+
+## Operation
+
+lindenii-forge-hookc collects the following information and sends it to
+the daemon:
+
+- All command-line arguments
+- All `GIT_*` environment variables
+- The raw hook stdin (e.g., old/new ref triplets for pre-receive)
+
+After sending this data, it waits for a one-byte status code from the daemon,
+which becomes `hookc`'s own exit status.
+
+If the daemon sends any output afterward, it is forwarded to standard error and
+will appear as `remote:` output to the user.
+
+## Known issues
+
+- The status byte from the daemon currently must be sent before any
+  stderr output.
+- Currently assumes stdin and stderr are pipes, which is not guaranteed
+  in future versions of Git.