data: add xbps.hook manpage

Author: Duncaen

data/Makefile

@@ -13,6 +13,7 @@ all:
 install:
 	install -d $(DESTDIR)$(MANDIR)/man5
 	install -m644 xbps.d.5 $(DESTDIR)$(MANDIR)/man5
+	install -m644 xbps.hook.5 $(DESTDIR)$(MANDIR)/man5
 	install -d $(DESTDIR)$(MANDIR)/man7
 	install -m644 xbps.7 $(DESTDIR)$(MANDIR)/man7
 	install -d $(DESTDIR)$(PKGCONFIGDIR)

data/xbps.hook.5

@@ -0,0 +1,158 @@
+.Dd December 22, 2025
+.Dt XBPS.HOOK 5
+.Os
+.Sh NAME
+.Nm xbps.hook
+.Nd XBPS hook configuration
+.Sh SYNOPSIS
+.Bl -item -compact
+.It
+/etc/xbps.d/hooks/*.hook
+.It
+/usr/share/xbps.d/hooks/*.hook
+.El
+.Sh DESCRIPTION
+The
+.Nm
+files are
+.So .ini Sc Ns -style
+configuration files to define hooks that execute commands at certain points of
+the xbps transactions
+.Po
+package updates,
+installs,
+and removals .
+.Pc
+.Pp
+Comments can be put anywhere in the file
+and using hashmarks
+.Pq Sq # ,
+or
+semi-colons
+.Pq Sq \&; ,
+and are continue to the end of the line.
+.Sh [HOOK] SECTION OPTIONS
+.Bl -tag -width -x
+.It Sy Name=
+Set the hook name used used for logging.
+.It Sy Exec= Ar command Op Ar args ...
+The command executed by the hook.
+The value is split into words,
+and passed to
+.Xr execv 3 ,
+spaces and tabs can be escaped using a
+backslash
+.Pq Sq \e .
+.It Ic When Ns = Ar option ...
+Defines when the hook is executed.
+The following values are supported
+and multiple values can be set by
+separating them with a space or defining
+the
+.Sy When
+option multiple times.
+Valid options are:
+.Bl -tag -width -x
+.It Ic PreTransaction
+Before all packages are installed,
+updated,
+or removed.
+.It Ic PostTransaction
+After all package are installed,
+updated,
+or removed.
+.El
+.El
+.Sh [MATCH] SECTION OPTIONS
+The
+.Sy Match
+section can be defined multiple times.
+.Bl -tag -width -x
+.It Ic Action Ns = Ar option ...
+One or more actions to match the target
+.Po
+.Ic Path
+or
+.Ic Package
+.Pc
+ against.
+Valid options are:
+.Bl -tag -width -x
+.It Ic Install
+If the file or package is being installed.
+.It Ic Remove
+If the file or package is being removed.
+.It Ic Update
+If the file or package is being updated.
+.It Ic Configure
+If the package is being updated.
+.El
+.It Ic Path Ns = Oo Ar path ... | Ar pattern ... Oc
+Match
+.Ar file
+or
+.Ar pattern .
+The value will be split into multiple words.
+For further details,
+see
+.Sx WORD SPLITTING .
+against files in the transaction.
+.It Ic Package Ns = Oo Ar pkgname ... | Ar pkgpattern ... Oc
+Match
+.Ar pkgname
+or
+.Ar pkgpattern
+against packages in the transaction.
+The value will be split into multiple words.
+For further details,
+see
+.Sx WORD SPLITTING .
+.El
+.Sh WORD SPLITTING
+Options which support multiple free text values will be split into separate
+words.
+The word boundaries are spaces
+.Pq Sq \~
+and tabs
+.Pq Sq \et .
+.Pp
+If a word contains a literal space
+.Pq Sq \~
+or tab
+.Pq Sq \et ,
+use a backslash
+.Pq Sq \e
+to escape the character.
+.Sh EXAMPLES
+The following example restarts the
+.Ic sshd
+service after the
+.Ic ssh
+package was updated.
+.Bd -literal -offset indent
+[Hook]
+Name = Restart sshd.
+When = PostTransaction
+Exec = sv restart /var/service/sshd
+
+[Match]
+Action = Update
+Package = ssh
+.Ed
+.Pp
+This example hook will sign the
+.Pa systemd-bootx64.efi
+file whenever it is being updated or installed.
+.Bd -literal -offset indent
+[Hook]
+Name = Sign the bootloader file.
+When = PostTransaction
+Exec = sbsign --key /etc/kernel/secure-boot.key.pem \e
+	--cert /etc/kernel/secure-boot.cert.pem \e
+	--output /usr/lib/systemd/boot/efi/systemd-bootx64.efi.signed \e
+	/usr/lib/systemd/boot/efi/systemd-bootx64.efi
+
+[Match]
+Action = Install Update
+Path = /usr/lib/systemd/boot/efi/systemd-bootx64.efi
+.Ed