summaryrefslogtreecommitdiff
path: root/doc/alpm-hooks.5.asciidoc
diff options
context:
space:
mode:
authorEli Schwartz <eschwartz@archlinux.org>2018-05-03 00:10:21 -0400
committerAllan McRae <allan@archlinux.org>2018-05-14 09:59:17 +1000
commit076b6184de2b20e9b26225d93f6f3a7030504109 (patch)
treeca0e375b9fd89d6b6ce40026b732985c4b335841 /doc/alpm-hooks.5.asciidoc
parent860e4c4943ad062bd0eff99f28e7d64804b3c08e (diff)
downloadpacman-076b6184de2b20e9b26225d93f6f3a7030504109.tar.xz
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 <eschwartz@archlinux.org> Signed-off-by: Allan McRae <allan@archlinux.org>
Diffstat (limited to 'doc/alpm-hooks.5.asciidoc')
-rw-r--r--doc/alpm-hooks.5.asciidoc128
1 files changed, 128 insertions, 0 deletions
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 = <Path|PkgName> (Required, Repeatable)
+
+[Action] (Required)
+Description = ... (Optional)
+When = PreTransaction|PostTransaction (Required)
+Exec = <Command> (Required)
+Depends = <PkgName> (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 =* <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
+-------
+
+*Description =* ...::
+ An optional description that describes the action being taken by the
+ hook for use in front-end output.
+
+*Exec =* <command>::
+ 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 =* <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.
+
+*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[]