From 076b6184de2b20e9b26225d93f6f3a7030504109 Mon Sep 17 00:00:00 2001 From: Eli Schwartz Date: Thu, 3 May 2018 00:10:21 -0400 Subject: Ensure better text editor automatic filetype detection Since we no longer use vim-specific modelines, use the .asciidoc file extension which is, well, reserved for asciidoc formatted files. This should presumably work everywhere without needing editor-specific workarounds and configuration. Also add a shebang to makepkg.conf to indicate it contains bash content. Signed-off-by: Eli Schwartz Signed-off-by: Allan McRae --- doc/alpm-hooks.5.asciidoc | 128 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 doc/alpm-hooks.5.asciidoc (limited to 'doc/alpm-hooks.5.asciidoc') diff --git a/doc/alpm-hooks.5.asciidoc b/doc/alpm-hooks.5.asciidoc new file mode 100644 index 00000000..1d19f96e --- /dev/null +++ b/doc/alpm-hooks.5.asciidoc @@ -0,0 +1,128 @@ +alpm-hooks(5) +============= + +NAME +---- + +alpm-hooks - alpm hook file format + +SYNOPSIS +-------- + +-------- +[Trigger] (Required, Repeatable) +Operation = Install|Upgrade|Remove (Required, Repeatable) +Type = File|Package (Required) +Target = (Required, Repeatable) + +[Action] (Required) +Description = ... (Optional) +When = PreTransaction|PostTransaction (Required) +Exec = (Required) +Depends = (Optional) +AbortOnFail (Optional, PreTransaction only) +NeedsTargets (Optional) +-------- + +DESCRIPTION +----------- + +libalpm provides the ability to specify hooks to run before or after +transactions based on the packages and/or files being modified. Hooks consist +of a single '[Action]' section describing the action to be run and one or more +'[Trigger]' section describing which transactions it should be run for. Hook +file names are required to have the suffix ".hook". Hooks are run in +alphabetical order of their file name. + +TRIGGERS +-------- + +Hooks must contain at least one '[Trigger]' section that determines which +transactions will cause the hook to run. If multiple trigger sections are +defined the hook will run if the transaction matches *any* of the triggers. + +*Operation =* Install|Upgrade|Remove:: + Select the type of operation to match targets against. May be specified + multiple times. Installations are considered an upgrade if the package or + file is already present on the system regardless of whether the new package + version is actually greater than the currently installed version. For File + triggers, this is true even if the file changes ownership from one package + to another. Required. + +*Type =* File|Package:: + Select whether targets are matched against transaction packages or files. + See CAVEATS for special notes regarding File triggers. Required. + +*Target =* :: + The file path or package name to match against the active transaction. + File paths refer to the files in the package archive; the installation root + should *not* be included in the path. Shell-style glob patterns are + allowed. It is possible to invert matches by prepending a file with an + exclamation mark. May be specified multiple times. Required. + +ACTIONS +------- + +*Description =* ...:: + An optional description that describes the action being taken by the + hook for use in front-end output. + +*Exec =* :: + Command to run. Command arguments are split on whitespace. Values + containing whitespace should be enclosed in quotes. Required. + +*When =* PreTransaction|PostTransaction:: + When to run the hook. Required. + +*Depends =* :: + Packages that must be installed for the hook to run. May be specified + multiple times. + +*AbortOnFail*:: + Causes the transaction to be aborted if the hook exits non-zero. Only + applies to PreTransaction hooks. + +*NeedsTargets*:: + Causes the list of matched trigger targets to be passed to the running hook + on 'stdin'. + +OVERRIDING HOOKS +---------------- + +Hooks may be overridden by placing a file with the same name in a higher +priority hook directory. Hooks may be disabled by overriding them with +a symlink to '/dev/null'. + +EXAMPLES +-------- + +-------- +# Force disks to sync to reduce the risk of data corruption + +[Trigger] +Operation = Install +Operation = Upgrade +Operation = Remove +Type = Package +Target = * + +[Action] +Depends = coreutils +When = PostTransaction +Exec = /usr/bin/sync +-------- + +CAVEATS +------- + +There are situations when file triggers may act in unexpected ways. Hooks are +triggered using the file list of the installed, upgraded, or removed package. +When installing or upgrading a file that is extracted with a '.pacnew' +extension, the original file name is used in triggering the hook. When +removing a package, all files owned by that package can trigger a hook whether +or not they were actually present on the file system before package removal. + +PostTransaction hooks will *not* run if the transaction fails to complete for +any reason. + +include::footer.asciidoc[] -- cgit v1.2.3-54-g00ecf