diff options
Diffstat (limited to 'doc/alpm-hooks.5.txt')
| -rw-r--r-- | doc/alpm-hooks.5.txt | 118 |
1 files changed, 118 insertions, 0 deletions
diff --git a/doc/alpm-hooks.5.txt b/doc/alpm-hooks.5.txt new file mode 100644 index 00000000..2986abf3 --- /dev/null +++ b/doc/alpm-hooks.5.txt @@ -0,0 +1,118 @@ +///// +vim:set ts=4 sw=4 syntax=asciidoc noet spell spelllang=en_us: +///// +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 = <Path|PkgName> (Required, Repeatable) + +[Action] (Required) +When = PreTransaction|PostTransaction (Required) +Exec = <Command> (Required) +Depends = <PkgName> (Optional) +AbortOnFail (Optional, PreTransaction only) +-------- + +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. + +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 =* <path|package>:: + 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 +------- + +*Exec =* /path/to/executable:: + Executable to run. Required. + +*When =* PreTransaction|PostTransaction:: + When to run the hook. Required. + +*Depends =* <package>:: + 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. + +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.txt[] |