You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

208 lines
9.0 KiB

  1. <?xml version="1.0" encoding="utf-8" standalone="no"?>
  2. <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  3. "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  4. <!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
  5. <!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
  6. <!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
  7. ]>
  8. <refentry>
  9. <refentryinfo>
  10. &apt-author.jgunthorpe;
  11. &apt-author.team;
  12. &apt-email;
  13. &apt-product;
  14. <!-- The last update date -->
  15. <date>2019-11-26T00:00:00Z</date>
  16. </refentryinfo>
  17. <refmeta>
  18. <refentrytitle>apt-patterns</refentrytitle>
  19. <manvolnum>7</manvolnum>
  20. <refmiscinfo class="manual">APT</refmiscinfo>
  21. </refmeta>
  22. <!-- Man page title -->
  23. <refnamediv>
  24. <refname>apt-patterns</refname>
  25. <refpurpose>Syntax and semantics of apt search patterns</refpurpose>
  26. </refnamediv>
  27. <refsect1><title>Description</title>
  28. <para>
  29. Starting with version 2.0, <command>APT</command> provides support for
  30. patterns, which can be used to query the apt cache for packages.
  31. </para>
  32. </refsect1>
  33. <refsect1>
  34. <title>Logic patterns</title>
  35. <para>
  36. These patterns provide the basic means to combine other patterns into
  37. more complex expressions, as well as <code>?true</code> and <code>?false</code>
  38. patterns.
  39. </para>
  40. <variablelist>
  41. <varlistentry><term><code>?and(PATTERN, PATTERN, ...)</code></term>
  42. <listitem><para>Selects objects where all specified patterns match.</para></listitem>
  43. </varlistentry>
  44. <varlistentry><term><code>?false</code></term>
  45. <listitem><para>Selects nothing.</para></listitem>
  46. </varlistentry>
  47. <varlistentry><term><code>?not(PATTERN)</code></term>
  48. <listitem><para>Selects objects where PATTERN does not match.</para></listitem>
  49. </varlistentry>
  50. <varlistentry><term><code>?or(PATTERN, PATTERN, ...)</code></term>
  51. <listitem><para>Selects objects where at least one of the specified patterns match.</para></listitem>
  52. </varlistentry>
  53. <varlistentry><term><code>?true</code></term>
  54. <listitem><para>Selects all objects.</para></listitem>
  55. </varlistentry>
  56. </variablelist>
  57. </refsect1>
  58. <refsect1>
  59. <title>Narrowing patterns</title>
  60. <para>
  61. </para>
  62. <variablelist>
  63. <varlistentry><term><code>?all-versions(PATTERN)</code></term>
  64. <listitem><para>Selects packages where all versions match PATTERN. When matching versions instead, same as PATTERN.</para></listitem>
  65. </varlistentry>
  66. <varlistentry><term><code>?any-version(PATTERN)</code></term>
  67. <listitem><para>Selects any version where the pattern matches on the version.</para>
  68. <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>
  69. </varlistentry>
  70. <varlistentry><term><code>?narrow(PATTERN...)</code></term>
  71. <listitem><para>Selects any version matching all PATTERNs, short for<code>?any-version(?and(PATTERN...))</code>.</para></listitem>
  72. </varlistentry>
  73. </variablelist>
  74. </refsect1>
  75. <refsect1>
  76. <title>Package patterns</title>
  77. <para>
  78. These patterns select specific packages.
  79. </para>
  80. <variablelist>
  81. <varlistentry><term><code>?architecture(WILDCARD)</code></term>
  82. <listitem><para>Selects packages matching the specified architecture, which may contain wildcards using any.</para></listitem>
  83. </varlistentry>
  84. <varlistentry><term><code>?automatic</code></term>
  85. <listitem><para>Selects packages that were installed automatically.</para></listitem>
  86. </varlistentry>
  87. <varlistentry><term><code>?broken</code></term>
  88. <listitem><para>Selects packages that have broken dependencies.</para></listitem>
  89. </varlistentry>
  90. <varlistentry><term><code>?config-files</code></term>
  91. <listitem><para>Selects packages that are not fully installed, but have solely residual configuration files left.</para></listitem>
  92. </varlistentry>
  93. <varlistentry><term><code>?essential</code></term>
  94. <listitem><para>Selects packages that have Essential: yes set in their control file.</para></listitem>
  95. </varlistentry>
  96. <varlistentry><term><code>?exact-name(NAME)</code></term>
  97. <listitem><para>Selects packages with the exact specified name.</para></listitem>
  98. </varlistentry>
  99. <varlistentry><term><code>?garbage</code></term>
  100. <listitem><para>Selects packages that can be removed automatically.</para></listitem>
  101. </varlistentry>
  102. <varlistentry><term><code>?installed</code></term>
  103. <listitem><para>Selects packages that are currently installed.</para></listitem>
  104. </varlistentry>
  105. <varlistentry><term><code>?name(REGEX)</code></term>
  106. <listitem><para>Selects packages where the name matches the given regular expression.</para></listitem>
  107. </varlistentry>
  108. <varlistentry><term><code>?obsolete</code></term>
  109. <listitem><para>Selects packages that no longer exist in repositories.</para></listitem>
  110. </varlistentry>
  111. <varlistentry><term><code>?upgradable</code></term>
  112. <listitem><para>Selects packages that can be upgraded (have a newer candidate).</para></listitem>
  113. </varlistentry>
  114. <varlistentry><term><code>?virtual</code></term>
  115. <listitem><para>Selects all virtual packages; that is packages without a version.
  116. These exist when they are referenced somewhere in the archive,
  117. for example because something depends on that name.</para></listitem>
  118. </varlistentry>
  119. </variablelist>
  120. </refsect1>
  121. <refsect1>
  122. <title>Version patterns</title>
  123. <para>
  124. These patterns select specific versions of a package.
  125. </para>
  126. <variablelist>
  127. <varlistentry><term><code>?archive(REGEX)</code></term>
  128. <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>
  129. </varlistentry>
  130. <varlistentry><term><code>?origin(REGEX)</code></term>
  131. <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>
  132. </varlistentry>
  133. <varlistentry><term><code>?section(REGEX)</code></term>
  134. <listitem><para>Selects versions where the section matches the specified regular expression.</para></listitem>
  135. </varlistentry>
  136. <varlistentry><term><code>?source-package(REGEX)</code></term>
  137. <listitem><para>Selects versions where the source package name matches the specified regular expression.</para></listitem>
  138. </varlistentry>
  139. <varlistentry><term><code>?source-version(REGEX)</code></term>
  140. <listitem><para>Selects versions where the source package version matches the specified regular expression.</para></listitem>
  141. </varlistentry>
  142. <varlistentry><term><code>?version(REGEX)</code></term>
  143. <listitem><para>Selects versions where the version string matching the specified regular expression.</para></listitem>
  144. </varlistentry>
  145. </variablelist>
  146. </refsect1>
  147. <refsect1><title>Examples</title>
  148. <variablelist>
  149. <varlistentry><term><code>apt remove ?garbage</code></term>
  150. <listitem><para>Remove all packages that are automatically installed and no longer needed - same as apt autoremove</para></listitem>
  151. </varlistentry>
  152. <varlistentry><term><code>apt purge ?config-files</code></term>
  153. <listitem><para>Purge all packages that only have configuration files left</para></listitem>
  154. </varlistentry>
  155. </variablelist>
  156. </refsect1>
  157. <refsect1><title>Migrating from aptitude</title>
  158. <para>
  159. Patterns in apt are heavily inspired by patterns in aptitude, but with some tweaks:
  160. </para>
  161. <itemizedlist>
  162. <listitem>
  163. <para>Only long forms &mdash; the ones starting with ? &mdash; are supported</para>
  164. </listitem>
  165. <listitem>
  166. <para>
  167. Syntax is uniform: If there is an opening parenthesis after a term, it is always assumed to be the beginning of an argument list.
  168. </para>
  169. <para>
  170. 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.
  171. </para>
  172. </listitem>
  173. <listitem>
  174. <para>Not all patterns are supported.</para>
  175. </listitem>
  176. <listitem>
  177. <para>Some additional patterns are available, for example, for finding gstreamer codecs.</para>
  178. </listitem>
  179. <listitem>
  180. <para>Escaping terms with <code>~</code> is not supported.</para>
  181. </listitem>
  182. <listitem>
  183. <para>A trailing comma is allowed in argument lists</para>
  184. </listitem>
  185. <listitem>
  186. <para>?narrow accepts infinite arguments</para>
  187. </listitem>
  188. </itemizedlist>
  189. </refsect1>
  190. <refsect1><title>See Also</title>
  191. <para>
  192. &apt-get;, &apt;
  193. </para>
  194. </refsect1>
  195. &manbugs;
  196. &manauthor;
  197. </refentry>