1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
|
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
<!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
]>
<refentry>
<refentryinfo>
&apt-author.jgunthorpe;
&apt-author.team;
&apt-email;
&apt-product;
<!-- The last update date -->
<date>2024-10-22T00:00:00Z</date>
</refentryinfo>
<refmeta>
<refentrytitle>apt-patterns</refentrytitle>
<manvolnum>7</manvolnum>
<refmiscinfo class="manual">APT</refmiscinfo>
</refmeta>
<!-- Man page title -->
<refnamediv>
<refname>apt-patterns</refname>
<refpurpose>Syntax and semantics of apt search patterns</refpurpose>
</refnamediv>
<refsect1><title>Description</title>
<para>
Starting with version 2.0, <command>APT</command> provides support for
patterns, which can be used to query the apt cache for packages.
</para>
</refsect1>
<refsect1>
<title>Logic patterns</title>
<para>
These patterns provide the basic means to combine other patterns into
more complex expressions, as well as <code>?true</code> and <code>?false</code>
patterns.
</para>
<variablelist>
<varlistentry><term><code>?and(PATTERN, PATTERN, ...)</code></term><term><code>PATTERN PATTERN ...</code></term>
<listitem><para>Selects objects where all specified patterns match.</para></listitem>
</varlistentry>
<varlistentry><term><code>?false</code></term><term><code>~F</code></term>
<listitem><para>Selects nothing.</para></listitem>
</varlistentry>
<varlistentry><term><code>?not(PATTERN)</code></term><term><code>!PATTERN</code></term>
<listitem><para>Selects objects where PATTERN does not match.</para></listitem>
</varlistentry>
<varlistentry><term><code>?or(PATTERN, PATTERN, ...)</code></term><term><code>PATTERN | PATTERN | ...</code></term>
<listitem><para>Selects objects where at least one of the specified patterns match.</para></listitem>
</varlistentry>
<varlistentry><term><code>?true</code></term><term><code>~T</code></term>
<listitem><para>Selects all objects.</para></listitem>
</varlistentry>
<varlistentry><term><code>(PATTERN)</code></term>
<listitem><para>Selects the same as <code>PATTERN</code>, can be used to work around precedence, for example, <code>(~ramd64|~ri386)~nfoo</code></para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Narrowing patterns</title>
<para>
</para>
<variablelist>
<varlistentry><term><code>?all-versions(PATTERN)</code></term>
<listitem><para>Selects packages where all versions match PATTERN. When matching versions instead, same as PATTERN.</para></listitem>
</varlistentry>
<varlistentry><term><code>?any-version(PATTERN)</code></term>
<listitem><para>Selects any version where the pattern matches on the version.</para>
<para>For example, while <code>?and(?version(1),?version(2))</code> matches a package which has one version containing 1 and one version containing 2, <code>?any-version(?and(?version(1),?version(2)))</code> restricts the <code>?and</code> to act on the same version.</para></listitem>
</varlistentry>
<varlistentry><term><code>?narrow(PATTERN...)</code></term>
<listitem><para>Selects any version matching all PATTERNs, short for <code>?any-version(?and(PATTERN...))</code>.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Package patterns</title>
<para>
These patterns select specific packages.
</para>
<variablelist>
<varlistentry><term><code>?architecture(WILDCARD)</code></term><term><code>~rWILDCARD</code></term>
<listitem><para>Selects packages matching the specified architecture, which may contain wildcards using any.</para></listitem>
</varlistentry>
<varlistentry><term><code>?automatic</code></term><term><code>~M</code></term>
<listitem><para>Selects packages that were installed automatically.</para></listitem>
</varlistentry>
<varlistentry><term><code>?broken</code></term><term><code>~b</code></term>
<listitem><para>Selects packages that have broken dependencies.</para></listitem>
</varlistentry>
<varlistentry><term><code>?config-files</code></term><term><code>~c</code></term>
<listitem><para>Selects packages that are not fully installed, but have solely residual configuration files left.</para></listitem>
</varlistentry>
<varlistentry><term><code>?essential</code></term><term><code>~E</code></term>
<listitem><para>Selects packages that have Essential: yes set in their control file.</para></listitem>
</varlistentry>
<varlistentry><term><code>?exact-name(NAME)</code></term>
<listitem><para>Selects packages with the exact specified name.</para></listitem>
</varlistentry>
<varlistentry><term><code>?garbage</code></term><term><code>~g</code></term>
<listitem><para>Selects packages that can be removed automatically.</para></listitem>
</varlistentry>
<varlistentry><term><code>?installed</code></term><term><code>~i</code></term>
<listitem><para>Selects packages that are currently installed. Since version 2.5.4, narrowing this pattern (see narrowing patterns above) makes it only match installed versions (see version patterns below).</para></listitem>
</varlistentry>
<varlistentry><term><code>?name(REGEX)</code></term><term><code>~nREGEX</code></term>
<listitem><para>Selects packages where the name matches the given regular expression.</para></listitem>
</varlistentry>
<varlistentry><term><code>?obsolete</code></term><term><code>~o</code></term>
<listitem><para>Selects packages that no longer exist in repositories.</para></listitem>
</varlistentry>
<varlistentry><term><code>?phasing</code></term>
<listitem><para>Selects packages that will be kept back in upgrades due to phasing.</para></listitem>
</varlistentry>
<varlistentry><term><code>?upgradable</code></term><term><code>~U</code></term>
<listitem><para>Selects packages that can be upgraded (have a newer candidate).</para></listitem>
</varlistentry>
<varlistentry><term><code>?virtual</code></term><term><code>~v</code></term>
<listitem><para>Selects all virtual packages; that is packages without a version.
These exist when they are referenced somewhere in the archive,
for example because something depends on that name.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Version patterns</title>
<para>
These patterns select specific versions of a package.
</para>
<variablelist>
<varlistentry><term><code>?archive(REGEX)</code></term><term><code>~AREGEX</code></term>
<listitem><para>Selects versions that come from the archive that matches the specified regular expression. Archive, here, means the values after <code>a=</code> in <command>apt-cache policy</command>.</para></listitem>
</varlistentry>
<varlistentry><term><code>?codename(REGEX)</code></term>
<listitem><para>Selects versions that come from the codename that matches the specified regular expression. Codename, here, means the values after <code>n=</code> in <command>apt-cache policy</command>.</para></listitem>
</varlistentry>
<varlistentry><term><code>?installed</code></term><term><code>~i</code></term>
<listitem><para>Selects package versions that are currently installed. Versions prior to 2.5.4 only matched at the package level, hence <code>?any-version(?installed?version(2.0))</code>matched even if 2.0 was not installed, but another version was.</para></listitem>
</varlistentry>
<varlistentry><term><code>?origin(REGEX)</code></term><term><code>~OREGEX</code></term>
<listitem><para>Selects versions that come from the origin that matches the specified regular expression. Origin, here, means the values after <code>o=</code> in <command>apt-cache policy</command>.</para></listitem>
</varlistentry>
<varlistentry><term><code>?section(REGEX)</code></term><term><code>~sREGEX</code></term>
<listitem><para>Selects versions where the section matches the specified regular expression.</para></listitem>
</varlistentry>
<varlistentry><term><code>?source-package(REGEX)</code></term><term><code>~eREGEX</code></term>
<listitem><para>Selects versions where the source package name matches the specified regular expression.</para></listitem>
</varlistentry>
<varlistentry><term><code>?source-version(REGEX)</code></term>
<listitem><para>Selects versions where the source package version matches the specified regular expression.</para></listitem>
</varlistentry>
<varlistentry><term><code>?version(REGEX)</code></term><term><code>~VREGEX</code></term>
<listitem><para>Selects versions where the version string matches the specified regular expression.</para></listitem>
</varlistentry>
<varlistentry><term><code>?priority(NAME)</code></term><term><code>~pNAME</code></term>
<listitem><para>Selects versions where the Priority string equals the given name.</para></listitem>
</varlistentry>
<varlistentry><term><code>?security</code></term>
<listitem><para>Selects packages that are a security update or succeed a security update.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>Package relationship patterns</title>
<para>These patterns match specific package versions that depend/conflict with some other packages.</para>
<variablelist>
<varlistentry>
<term><code>?depends(PATTERN)</code></term><term><code>~DPATTERN</code></term>
<term><code>?pre-depends(PATTERN)</code></term><term><code>~DPre-Depends:PATTERN</code></term>
<term><code>?suggests(PATTERN)</code></term><term><code>~DSuggests:PATTERN</code></term>
<term><code>?recommends(PATTERN)</code></term><term><code>~DRecommends:PATTERN</code></term>
<term><code>?conflicts(PATTERN)</code></term><term><code>~DConflicts:PATTERN</code></term>
<term><code>?replaces(PATTERN)</code></term><term><code>~DReplaces:PATTERN</code></term>
<term><code>?obsoletes(PATTERN)</code></term><term><code>~DObsoletes:PATTERN</code></term>
<term><code>?breaks(PATTERN)</code></term><term><code>~DBreaks:PATTERN</code></term>
<term><code>?enhances(PATTERN)</code></term><term><code>~DEnhances:PATTERN</code></term>
<listitem><para>Selects versions depending/pre-depending/suggesting/recommending/conflicting/etc on/with/ packages matching PATTERN.</para></listitem>
</varlistentry>
<varlistentry>
<term><code>?reverse-<replaceable>depType</replaceable>(PATTERN)</code></term>
<term><code>~R<replaceable>DepType</replaceable>:PATTERN</code></term>
<listitem><para>Opposite of <code>?depends</code> and friends - selects all packages that have reverse-dependencies (versions) matching PATTERN.</para>
<para><replaceable>depType</replaceable> is one of the dependency types such as <code>depends</code>, so that we don't have to repeat the entire list from the first paragraph here.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>Examples</title>
<variablelist>
<varlistentry><term><code>apt remove ?garbage</code></term>
<listitem><para>Remove all packages that are automatically installed and no longer needed - same as apt autoremove</para></listitem>
</varlistentry>
<varlistentry><term><code>apt purge ?config-files</code></term>
<listitem><para>Purge all packages that only have configuration files left</para></listitem>
</varlistentry>
<varlistentry><term><code>apt list '~i !~M (~slibs|~sperl|~spython)'</code></term>
<listitem><para>List all manually-installed packages in sections matching libs, perl, or python.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>Migrating from aptitude</title>
<para>
Patterns in apt are heavily inspired by patterns in aptitude, but with some tweaks:
</para>
<itemizedlist>
<listitem>
<para>
Syntax is uniform: If there is an opening parenthesis after a term, it is always assumed to be the beginning of an argument list.
</para>
<para>
In aptitude, a syntactic form <code>"?foo(bar)"</code> could mean <code>"?and(?foo,bar)"</code> if foo does not take an argument. In APT, this will cause an error.
</para>
</listitem>
<listitem>
<para>Not all patterns are supported.</para>
</listitem>
<listitem>
<para>Some additional patterns are available, for example, for finding gstreamer codecs.</para>
</listitem>
<listitem>
<para>Escaping terms with <code>~</code> is not supported.</para>
</listitem>
<listitem>
<para>A trailing comma is allowed in argument lists</para>
</listitem>
<listitem>
<para>?narrow accepts infinite arguments</para>
</listitem>
<listitem>
<para><code>foo</code> cannot be used as a shortform for <code>?name(foo)</code>, as this can cause typos to go unnoticed:
Consider <code>?and(...,~poptional)</code>:
this requires the package to have <code>required</code> priority, but
if you do not type the <code>~</code>, it would require the package name to contain <code>poptional</code>.</para>
</listitem>
<listitem>
<para>Dependency types for ~D and related operators need to be specified in the canonical case.</para>
</listitem>
</itemizedlist>
</refsect1>
<refsect1><title>See Also</title>
<para>
&apt-get;, &apt;
</para>
</refsect1>
&manbugs;
&manauthor;
</refentry>
|
