diff options
| -rw-r--r-- | doc/.gitignore | 1 | ||||
| -rw-r--r-- | doc/Makefile.am | 4 | ||||
| -rw-r--r-- | doc/alpm-hooks.5.txt | 118 |
3 files changed, 123 insertions, 0 deletions
diff --git a/doc/.gitignore b/doc/.gitignore index ad496ce0..2eae9e4b 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,3 +1,4 @@ +alpm-hooks.5 PKGBUILD.5 libalpm.3 makepkg.8 diff --git a/doc/Makefile.am b/doc/Makefile.am index 60a70b3e..90d90f33 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -4,6 +4,7 @@ # man_MANS if --enable-asciidoc and/or --enable-doxygen are used. ASCIIDOC_MANS = \ + alpm-hooks.5 \ pacman.8 \ makepkg.8 \ makepkg-template.1 \ @@ -20,6 +21,7 @@ ASCIIDOC_MANS = \ DOXYGEN_MANS = $(wildcard man3/*.3) HTML_MANPAGES = \ + alpm-hooks.5.html \ pacman.8.html \ makepkg.8.html \ makepkg-template.1.html \ @@ -46,6 +48,7 @@ HTML_DOCS = \ EXTRA_DIST = \ asciidoc.conf \ asciidoc-override.css \ + alpm-hooks.5.txt \ pacman.8.txt \ makepkg.8.txt \ makepkg-template.1.txt \ @@ -147,6 +150,7 @@ $(HTML_OTHER): asciidoc.conf Makefile.am %.3.html: ASCIIDOC_OPTS += -d manpage # Dependency rules +alpm-hooks.5 alpm-hooks.5.html: alpm-hooks.5.txt pacman.8 pacman.8.html: pacman.8.txt makepkg.8 makepkg.8.html: makepkg.8.txt makepkg-template.1 makepkg-template.1.html: makepkg-template.1.txt 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[] |