Add hookc.1 man page

1 files changed, 74 insertions, 0 deletions

diff --git a/hookc/hookc.1 b/hookc/hookc.1
new file mode 100644
index 0000000..7be5380
--- /dev/null
+++ b/hookc/hookc.1
@@ -0,0 +1,74 @@
+.\" SPDX-License-Identifier: AGPL-3.0-only
+.\" SPDX-FileContributor: Runxi Yu <https://runxiyu.org>
+.Dd March 30, 2025
+.Dt HOOKC 1
+.Os Lindenii Forge
+.Sh NAME
+.Nm hookc
+.Nd helper binary to delegate Git hook behavior to the forge daemon
+.Sh SYNOPSIS
+.Nm
+.Op Ar argument ...
+.Sh DESCRIPTION
+.Nm
+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.
+.Pp
+It is intended to be invoked by
+.Xr git-receive-pack 1
+for hooks such as
+.Pa pre-receive ,
+.Pa update ,
+and
+.Pa post-receive .
+.Sh ENVIRONMENT
+.Bl -tag -width Ds
+.It Ev LINDENII_FORGE_HOOKS_SOCKET_PATH
+Absolute path to the UNIX domain socket on which the daemon is listening.
+.It Ev LINDENII_FORGE_HOOKS_COOKIE
+64-character authentication cookie used to validate the hook client to the daemon.
+.El
+.Sh OPERATION
+.Nm
+collects the following information and sends it to the daemon:
+.Bl -bullet
+.It
+All command-line arguments
+.It
+All
+.Ev GIT_*
+environment variables
+.It
+The raw hook
+.Pa stdin
+(e.g., old/new ref triplets for
+.Pa pre-receive )
+.El
+.Pp
+After sending this data, it waits for a one-byte status code from the daemon,
+which becomes
+.Nm Ns 's
+own exit status.
+.Pp
+If the daemon sends any output afterward, it is forwarded to standard error
+and will appear as
+.Dq remote:
+output to the user.
+.Sh BUGS
+.Bl -bullet
+.It
+The status byte from the daemon currently must be sent before any stderr output.
+.It
+Currently assumes
+.Pa stdin
+and
+.Pa stderr
+are pipes, which is not guaranteed in future versions of Git.
+.El
+.Sh AUTHORS
+.An Runxi Yu Aq Mt https://runxiyu.org
+.An Test_User Aq Mt hax@runxiyu.org
+.Sh SEE ALSO
+.Xr git-receive-pack 1 ,
+.Xr forge 1