Debian Codegraph @

upstream/debian-unstable/man5/pacman-hooks.5

raw
1 '\" t
2 .\" Title: alpm-hooks
3 .\" Author: [see the "Authors" section]
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\" Date: 11-11-1111
6 .\" Manual: Pacman Manual
7 .\" Source: Pacman 7.1.0
8 .\" Language: English
9 .\"
10 .TH "ALPM\-HOOKS" "5" "11\-11\-1111" "Pacman 7\&.1\&.0" "Pacman Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 alpm-hooks \- alpm hook file format
32 .SH "SYNOPSIS"
33 .sp
34 .nf
35 [Trigger] (Required, Repeatable)
36 Operation = Install|Upgrade|Remove (Required, Repeatable)
37 Type = Path|Package (Required)
38 Target = <Path|PkgName> (Required, Repeatable)
39
40 [Action] (Required)
41 Description = \&.\&.\&. (Optional)
42 When = PreTransaction|PostTransaction (Required)
43 Exec = <Command> (Required)
44 Depends = <PkgName> (Optional)
45 AbortOnFail (Optional, PreTransaction only)
46 NeedsTargets (Optional)
47 .fi
48 .SH "DESCRIPTION"
49 .sp
50 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 \fI[Action]\fR section describing the action to be run and one or more \fI[Trigger]\fR section describing which transactions it should be run for\&.
51 .sp
52 Hooks are read from files located in the system hook directory /usr/share/libalpm/hooks, and additional custom directories specified in \fBpacman.conf\fR(5) (the default is /etc/pacman\&.d/hooks)\&. The file names are required to have the suffix "\&.hook"\&. Hooks are run in alphabetical order of their file name, where the ordering ignores the suffix\&.
53 .SH "TRIGGERS"
54 .sp
55 Hooks must contain at least one \fI[Trigger]\fR 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 \fBany\fR of the triggers\&.
56 .PP
57 \fBOperation =\fR Install|Upgrade|Remove
58 .RS 4
59 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 Path triggers, this is true even if the file changes ownership from one package to another\&. Required\&.
60 .RE
61 .PP
62 \fBType =\fR Path|Package
63 .RS 4
64 Select whether targets are matched against transaction packages or files\&. See CAVEATS for special notes regarding Path triggers\&.
65 \fIFile\fR
66 is a deprecated alias for
67 \fIPath\fR
68 and will be removed in a future release\&. Required\&.
69 .RE
70 .PP
71 \fBTarget =\fR <path|package>
72 .RS 4
73 The path or package name to match against the active transaction\&. Paths refer to the files in the package archive; the installation root should
74 \fBnot\fR
75 be included in the path\&. Shell\-style glob patterns are allowed\&. It is possible to invert matches by prepending a target with an exclamation mark\&. May be specified multiple times\&. Required\&.
76 .RE
77 .SH "ACTIONS"
78 .PP
79 \fBDescription =\fR \&...
80 .RS 4
81 An optional description that describes the action being taken by the hook for use in front\-end output\&.
82 .RE
83 .PP
84 \fBExec =\fR <command>
85 .RS 4
86 Command to run\&. Command arguments are split on whitespace\&. Values containing whitespace should be enclosed in quotes\&. Required\&.
87 .RE
88 .PP
89 \fBWhen =\fR PreTransaction|PostTransaction
90 .RS 4
91 When to run the hook\&. Required\&.
92 .RE
93 .PP
94 \fBDepends =\fR <package>
95 .RS 4
96 Packages that must be installed for the hook to run\&. May be specified multiple times\&.
97 .RE
98 .PP
99 \fBAbortOnFail\fR
100 .RS 4
101 Causes the transaction to be aborted if the hook exits non\-zero\&. Only applies to PreTransaction hooks\&.
102 .RE
103 .PP
104 \fBNeedsTargets\fR
105 .RS 4
106 Causes the list of matched trigger targets to be passed to the running hook on
107 \fIstdin\fR\&.
108 .RE
109 .SH "OVERRIDING HOOKS"
110 .sp
111 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 \fI/dev/null\fR\&.
112 .SH "EXAMPLES"
113 .sp
114 .if n \{\
115 .RS 4
116 .\}
117 .nf
118 # Force disks to sync to reduce the risk of data corruption
119
120 [Trigger]
121 Operation = Install
122 Operation = Upgrade
123 Operation = Remove
124 Type = Package
125 Target = *
126
127 [Action]
128 Depends = coreutils
129 When = PostTransaction
130 Exec = /usr/bin/sync
131 .fi
132 .if n \{\
133 .RE
134 .\}
135 .SH "CAVEATS"
136 .sp
137 There are situations when path 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 \fI\&.pacnew\fR 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\&.
138 .sp
139 PostTransaction hooks will \fBnot\fR run if the transaction fails to complete for any reason\&.
140 .sp
141 See the pacman website at https://archlinux\&.org/pacman/ for current information on pacman and its related tools\&.
142 .SH "BUGS"
143 .sp
144 Bugs? You must be kidding; there are no bugs in this software\&. But if we happen to be wrong, please report them to the issue tracker at https://gitlab\&.archlinux\&.org/pacman/pacman/\-/issues with specific information such as your command\-line, the nature of the bug, and even the package database if it helps\&.
145 .SH "AUTHORS"
146 .sp
147 Current maintainers:
148 .sp
149 .RS 4
150 .ie n \{\
151 \h'-04'\(bu\h'+03'\c
152 .\}
153 .el \{\
154 .sp -1
155 .IP \(bu 2.3
156 .\}
157 Allan McRae <allan@archlinux\&.org>
158 .RE
159 .sp
160 .RS 4
161 .ie n \{\
162 \h'-04'\(bu\h'+03'\c
163 .\}
164 .el \{\
165 .sp -1
166 .IP \(bu 2.3
167 .\}
168 Andrew Gregory <andrew\&.gregory\&.8@gmail\&.com>
169 .RE
170 .sp
171 .RS 4
172 .ie n \{\
173 \h'-04'\(bu\h'+03'\c
174 .\}
175 .el \{\
176 .sp -1
177 .IP \(bu 2.3
178 .\}
179 Morgan Adamiec <morganamilo@archlinux\&.org>
180 .RE
181 .sp
182 Past major contributors:
183 .sp
184 .RS 4
185 .ie n \{\
186 \h'-04'\(bu\h'+03'\c
187 .\}
188 .el \{\
189 .sp -1
190 .IP \(bu 2.3
191 .\}
192 Judd Vinet <jvinet@zeroflux\&.org>
193 .RE
194 .sp
195 .RS 4
196 .ie n \{\
197 \h'-04'\(bu\h'+03'\c
198 .\}
199 .el \{\
200 .sp -1
201 .IP \(bu 2.3
202 .\}
203 Aurelien Foret <aurelien@archlinux\&.org>
204 .RE
205 .sp
206 .RS 4
207 .ie n \{\
208 \h'-04'\(bu\h'+03'\c
209 .\}
210 .el \{\
211 .sp -1
212 .IP \(bu 2.3
213 .\}
214 Aaron Griffin <aaron@archlinux\&.org>
215 .RE
216 .sp
217 .RS 4
218 .ie n \{\
219 \h'-04'\(bu\h'+03'\c
220 .\}
221 .el \{\
222 .sp -1
223 .IP \(bu 2.3
224 .\}
225 Dan McGee <dan@archlinux\&.org>
226 .RE
227 .sp
228 .RS 4
229 .ie n \{\
230 \h'-04'\(bu\h'+03'\c
231 .\}
232 .el \{\
233 .sp -1
234 .IP \(bu 2.3
235 .\}
236 Xavier Chantry <shiningxc@gmail\&.com>
237 .RE
238 .sp
239 .RS 4
240 .ie n \{\
241 \h'-04'\(bu\h'+03'\c
242 .\}
243 .el \{\
244 .sp -1
245 .IP \(bu 2.3
246 .\}
247 Nagy Gabor <ngaba@bibl\&.u\-szeged\&.hu>
248 .RE
249 .sp
250 .RS 4
251 .ie n \{\
252 \h'-04'\(bu\h'+03'\c
253 .\}
254 .el \{\
255 .sp -1
256 .IP \(bu 2.3
257 .\}
258 Dave Reisner <dreisner@archlinux\&.org>
259 .RE
260 .sp
261 .RS 4
262 .ie n \{\
263 \h'-04'\(bu\h'+03'\c
264 .\}
265 .el \{\
266 .sp -1
267 .IP \(bu 2.3
268 .\}
269 Eli Schwartz <eschwartz@archlinux\&.org>
270 .RE
271 .sp
272 For additional contributors, use git shortlog \-s on the pacman\&.git repository\&.