doc/apt_preferences.5.xml

   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
   5 <!ENTITY % aptent SYSTEM "apt.ent">
   6 %aptent;
   7
   8 <!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent">
   9 %aptverbatiment;
  10
  11 <!ENTITY % aptvendor SYSTEM "apt-vendor.ent">
  12 %aptvendor;
  13 ]>
  14
  15 <refentry>
  16
  17  <refentryinfo>
  18    &apt-author.team;
  19    &apt-email;
  20    &apt-product;
  21    <!-- The last update date -->
  22    <date>2012-06-09T00:00:00Z</date>
  23  </refentryinfo>
  24
  25  <refmeta>
  26    <refentrytitle>apt_preferences</refentrytitle>
  27    <manvolnum>5</manvolnum>
  28    <refmiscinfo class="manual">APT</refmiscinfo>
  29  </refmeta>
  30
  31  <!-- Man page title -->
  32  <refnamediv>
  33     <refname>apt_preferences</refname>
  34     <refpurpose>Preference control file for APT</refpurpose>
  35  </refnamediv>
  36
  37 <refsect1>
  38 <title>Description</title>
  39 <para>The APT preferences file <filename>/etc/apt/preferences</filename>
  40 and the fragment files in the <filename>/etc/apt/preferences.d/</filename>
  41 folder can be used to control which versions of packages will be selected
  42 for installation.</para>
  43
  44 <para>Several versions of a package may be available for installation when
  45 the &sources-list; file contains references to more than one distribution
  46 (for example, <literal>stable</literal> and <literal>testing</literal>).
  47 APT assigns a priority to each version that is available.
  48 Subject to dependency constraints, <command>apt-get</command> selects the
  49 version with the highest priority for installation.
  50 The APT preferences override the priorities that APT assigns to
  51 package versions by default, thus giving the user control over which
  52 one is selected for installation.</para>
  53
  54 <para>Several instances of the same version of a package may be available when
  55 the &sources-list; file contains references to more than one source.
  56 In this case <command>apt-get</command> downloads the instance listed
  57 earliest in the &sources-list; file.
  58 The APT preferences do not affect the choice of instance, only
  59 the choice of version.</para>
  60
  61 <para>Preferences are a strong power in the hands of a system administrator
  62 but they can become also their biggest nightmare if used without care!
  63 APT will not question the preferences, so wrong settings can
  64 lead to uninstallable packages or wrong decisions while upgrading packages.
  65 Even more problems will arise if multiple distribution releases are mixed
  66 without a good understanding of the following paragraphs.
  67 Packages included in a specific release aren't tested in (and
  68 therefore don't always work as expected in) older or newer releases, or
  69 together with other packages from different releases.
  70 You have been warned.</para>
  71
  72 <para>Note that the files in the <filename>/etc/apt/preferences.d</filename>
  73 directory are parsed in alphanumeric ascending order and need to obey the
  74 following naming convention: The files have either no or "<literal>pref</literal>"
  75 as filename extension and only contain alphanumeric, hyphen (-),
  76 underscore (_) and period (.) characters.
  77 Otherwise APT will print a notice that it has ignored a file, unless that
  78 file matches a pattern in the <literal>Dir::Ignore-Files-Silently</literal>
  79 configuration list - in which case it will be silently ignored.</para>
  80
  81 <refsect2><title>APT's Default Priority Assignments</title>
  82
  83 <para>If there is no preferences file or if there is no entry in the file
  84 that applies to a particular version then the priority assigned to that
  85 version is the priority of the distribution to which that version
  86 belongs.  It is possible to single out a distribution, "the target release",
  87 which receives a higher priority than other distributions do by default.
  88 The target release can be set on the <command>apt-get</command> command
  89 line or in the APT configuration file <filename>/etc/apt/apt.conf</filename>.
  90 Note that this has precedence over any general priority you set in the
  91 <filename>/etc/apt/preferences</filename> file described later, but not
  92 over specifically pinned packages.
  93 For example,
  94
  95 <programlisting>
  96 <command>apt-get install -t testing <replaceable>some-package</replaceable></command>
  97 </programlisting>
  98 <programlisting>
  99 APT::Default-Release "stable";
 100 </programlisting>
 101 </para>
 102
 103 <para>If the target release has been specified then APT uses the following
 104 algorithm to set the priorities of the versions of a package.  Assign:
 105
 106 <variablelist>
 107 <varlistentry>
 108 <term>priority 1</term>
 109 <listitem><simpara>to the versions coming from archives which in their <filename>Release</filename>
 110 files are marked as "NotAutomatic: yes" but <emphasis>not</emphasis> as "ButAutomaticUpgrades: yes"
 111 like the Debian <literal>experimental</literal> archive.</simpara></listitem>
 112 </varlistentry>
 113
 114 <varlistentry>
 115 <term>priority 100</term>
 116 <listitem><simpara>to the version that is already installed (if any) and to the versions coming
 117 from archives which in their <filename>Release</filename> files are marked as "NotAutomatic: yes" and
 118 "ButAutomaticUpgrades: yes" like the Debian backports archive since <literal>squeeze-backports</literal>.
 119 </simpara></listitem>
 120 </varlistentry>
 121
 122 <varlistentry>
 123 <term>priority 500</term>
 124 <listitem><simpara>to the versions that are not installed and do not belong to the target release.</simpara></listitem>
 125 </varlistentry>
 126
 127 <varlistentry>
 128 <term>priority 990</term>
 129 <listitem><simpara>to the versions that are not installed and belong to the target release.</simpara></listitem>
 130 </varlistentry>
 131 </variablelist>
 132 </para>
 133
 134 <para>If the target release has not been specified then APT simply assigns
 135 priority 100 to all installed package versions and priority 500 to all
 136 uninstalled package versions, except versions coming from archives which
 137 in their <filename>Release</filename> files are marked as "NotAutomatic: yes" -
 138 these versions get the priority 1 or priority 100 if it is additionally marked
 139 as "ButAutomaticUpgrades: yes".</para>
 140
 141 <para>APT then applies the following rules, listed in order of precedence,
 142 to determine which version of a package to install.
 143 <itemizedlist>
 144 <listitem><simpara>Never downgrade unless the priority of an available
 145 version exceeds 1000.  ("Downgrading" is installing a less recent version
 146 of a package in place of a more recent version.  Note that none of APT's
 147 default priorities exceeds 1000; such high priorities can only be set in
 148 the preferences file.  Note also that downgrading a package
 149 can be risky.)</simpara></listitem>
 150 <listitem><simpara>Install the highest priority version.</simpara></listitem>
 151 <listitem><simpara>If two or more versions have the same priority,
 152 install the most recent one (that is, the one with the higher version
 153 number).</simpara></listitem>
 154 <listitem><simpara>If two or more versions have the same priority and
 155 version number but either the packages differ in some of their metadata or the
 156 <literal>--reinstall</literal> option is given, install the uninstalled one.</simpara></listitem>
 157 </itemizedlist>
 158 </para>
 159
 160 <para>In a typical situation, the installed version of a package (priority 100)
 161 is not as recent as one of the versions available from the sources listed in
 162 the &sources-list; file (priority 500 or 990).  Then the package will be upgraded
 163 when <command>apt-get install <replaceable>some-package</replaceable></command>
 164 or <command>apt-get upgrade</command> is executed.
 165 </para>
 166
 167 <para>More rarely, the installed version of a package is <emphasis>more</emphasis> recent
 168 than any of the other available versions.  The package will not be downgraded
 169 when <command>apt-get install <replaceable>some-package</replaceable></command>
 170 or <command>apt-get upgrade</command> is executed.</para>
 171
 172 <para>Sometimes the installed version of a package is more recent than the
 173 version belonging to the target release, but not as recent as a version
 174 belonging to some other distribution.  Such a package will indeed be upgraded
 175 when <command>apt-get install <replaceable>some-package</replaceable></command>
 176 or <command>apt-get upgrade</command> is executed,
 177 because at least <emphasis>one</emphasis> of the available versions has a higher
 178 priority than the installed version.</para>
 179 </refsect2>
 180
 181 <refsect2><title>The Effect of APT Preferences</title>
 182
 183 <para>The APT preferences file allows the system administrator to control the
 184 assignment of priorities.  The file consists of one or more multi-line records
 185 separated by blank lines.  Records can have one of two forms, a specific form
 186 and a general form.
 187 <itemizedlist>
 188 <listitem>
 189 <simpara>The specific form assigns a priority (a "Pin-Priority") to one or more
 190 specified packages with a specified version or version range.  For example,
 191 the following record assigns a high priority to all versions of
 192 the <filename>perl</filename> package whose version number begins with "<literal>&good-perl;</literal>".
 193 Multiple packages can be separated by spaces.</simpara>
 194
 195 <programlisting>
 196 Package: perl
 197 Pin: version &good-perl;*
 198 Pin-Priority: 1001
 199 </programlisting>
 200 </listitem>
 201
 202 <listitem><simpara>The general form assigns a priority to all of the package versions in a
 203 given distribution (that is, to all the versions of packages that are
 204 listed in a certain <filename>Release</filename> file) or to all of the package
 205 versions coming from a particular Internet site, as identified by the
 206 site's fully qualified domain name.</simpara>
 207
 208 <simpara>This general-form entry in the APT preferences file applies only
 209 to groups of packages.  For example, the following record assigns a high
 210 priority to all package versions available from the local site.</simpara>
 211
 212 <programlisting>
 213 Package: *
 214 Pin: origin ""
 215 Pin-Priority: 999
 216 </programlisting>
 217
 218 <simpara>A note of caution: the keyword used here is "<literal>origin</literal>"
 219 which can be used to match a hostname. The following record will assign a high priority
 220 to all versions available from the server identified by the hostname "ftp.de.debian.org"</simpara>
 221 <programlisting>
 222 Package: *
 223 Pin: origin "ftp.de.debian.org"
 224 Pin-Priority: 999
 225 </programlisting>
 226 <simpara>This should <emphasis>not</emphasis> be confused with the Origin of a distribution as
 227 specified in a <filename>Release</filename> file.  What follows the "Origin:" tag
 228 in a <filename>Release</filename> file is not an Internet address
 229 but an author or vendor name, such as "Debian" or "Ximian".</simpara>
 230
 231 <simpara>The following record assigns a low priority to all package versions
 232 belonging to any distribution whose Archive name is "<literal>unstable</literal>".</simpara>
 233
 234 <programlisting>
 235 Package: *
 236 Pin: release a=unstable
 237 Pin-Priority: 50
 238 </programlisting>
 239
 240 <simpara>The following record assigns a high priority to all package versions
 241 belonging to any distribution whose Codename is "<literal>&testing-codename;</literal>".</simpara>
 242
 243 <programlisting>
 244 Package: *
 245 Pin: release n=&testing-codename;
 246 Pin-Priority: 900
 247 </programlisting>
 248
 249 <simpara>The following record assigns a high priority to all package versions
 250 belonging to any release whose Archive name is "<literal>stable</literal>"
 251 and whose release Version number is "<literal>&stable-version;</literal>".</simpara>
 252
 253 <programlisting>
 254 Package: *
 255 Pin: release a=stable, v=&stable-version;
 256 Pin-Priority: 500
 257 </programlisting>
 258 </listitem>
 259 </itemizedlist>
 260 </para>
 261
 262 </refsect2>
 263
 264 <refsect2><title>Regular expressions and &glob; syntax</title>
 265 <para>
 266 APT also supports pinning by &glob; expressions, and regular
 267 expressions surrounded by slashes. For example, the following
 268 example assigns the priority 500 to all packages from
 269 experimental where the name starts with gnome (as a &glob;-like
 270 expression) or contains the word kde (as a POSIX extended regular
 271 expression surrounded by slashes).
 272 </para>
 273
 274 <programlisting>
 275 Package: gnome* /kde/
 276 Pin: release n=experimental
 277 Pin-Priority: 500
 278 </programlisting>
 279
 280 <para>
 281 The rule for those expressions is that they can occur anywhere
 282 where a string can occur. Thus, the following pin assigns the
 283 priority 990 to all packages from a release starting with &ubuntu-codename;.
 284 </para>
 285
 286 <programlisting>
 287 Package: *
 288 Pin: release n=&ubuntu-codename;*
 289 Pin-Priority: 990
 290 </programlisting>
 291
 292 <para>
 293 If a regular expression occurs in a <literal>Package</literal> field,
 294 the behavior is the same as if this regular expression were replaced
 295 with a list of all package names it matches. It is undecided whether
 296 this will change in the future; thus you should always list wild-card
 297 pins first, so later specific pins override it.
 298
 299 The pattern "<literal>*</literal>" in a Package field is not considered
 300 a &glob; expression in itself.
 301 </para>
 302 </refsect2>
 303
 304
 305
 306
 307
 308 <refsect2>
 309 <title>How APT Interprets Priorities</title>
 310
 311 <para>
 312 Priorities (P) assigned in the APT preferences file must be positive
 313 or negative integers.  They are interpreted as follows (roughly speaking):
 314
 315 <variablelist>
 316 <varlistentry>
 317 <term>P &gt;= 1000</term>
 318 <listitem><simpara>causes a version to be installed even if this
 319 constitutes a downgrade of the package</simpara></listitem>
 320 </varlistentry>
 321 <varlistentry>
 322 <term>990 &lt;= P &lt; 1000</term>
 323 <listitem><simpara>causes a version to be installed
 324 even if it does not come from the target release,
 325 unless the installed version is more recent</simpara></listitem>
 326 </varlistentry>
 327 <varlistentry>
 328 <term>500 &lt;= P &lt; 990</term>
 329 <listitem><simpara>causes a version to be installed
 330 unless there is a version available belonging to the target release
 331 or the installed version is more recent</simpara></listitem>
 332 </varlistentry>
 333 <varlistentry>
 334 <term>100 &lt;= P &lt; 500</term>
 335 <listitem><simpara>causes a version to be installed
 336 unless there is a version available belonging to some other
 337 distribution or the installed version is more recent</simpara></listitem>
 338 </varlistentry>
 339 <varlistentry>
 340 <term>0 &lt; P &lt; 100</term>
 341 <listitem><simpara>causes a version to be installed
 342 only if there is no installed version of the package</simpara></listitem>
 343 </varlistentry>
 344 <varlistentry>
 345 <term>P &lt; 0</term>
 346 <listitem><simpara>prevents the version from being installed</simpara></listitem>
 347 </varlistentry>
 348 </variablelist>
 349 </para>
 350
 351 <para>If any specific-form records match an available package version then the
 352 first such record determines the priority of the package version.
 353 Failing that,
 354 if any general-form records match an available package version then the
 355 first such record determines the priority of the package version.</para>
 356
 357 <para>For example, suppose the APT preferences file contains the three
 358 records presented earlier:</para>
 359
 360 <programlisting>
 361 Package: perl
 362 Pin: version &good-perl;*
 363 Pin-Priority: 1001
 364
 365 Package: *
 366 Pin: origin ""
 367 Pin-Priority: 999
 368
 369 Package: *
 370 Pin: release unstable
 371 Pin-Priority: 50
 372 </programlisting>
 373
 374 <para>Then:
 375 <itemizedlist>
 376 <listitem><simpara>The most recent available version of the <literal>perl</literal>
 377 package will be installed, so long as that version's version number begins
 378 with "<literal>&good-perl;</literal>".  If <emphasis>any</emphasis> &good-perl;* version of <literal>perl</literal> is
 379 available and the installed version is &bad-perl;*, then <literal>perl</literal> will be
 380 downgraded.</simpara></listitem>
 381 <listitem><simpara>A version of any package other than <literal>perl</literal>
 382 that is available from the local system has priority over other versions,
 383 even versions belonging to the target release.
 384 </simpara></listitem>
 385 <listitem><simpara>A version of a package whose origin is not the local
 386 system but some other site listed in &sources-list; and which belongs to
 387 an <literal>unstable</literal> distribution is only installed if it is selected
 388 for installation and no version of the package is already installed.
 389 </simpara></listitem>
 390 </itemizedlist>
 391 </para>
 392 </refsect2>
 393
 394 <refsect2>
 395 <title>Determination of Package Version and Distribution Properties</title>
 396
 397 <para>The locations listed in the &sources-list; file should provide
 398 <filename>Packages</filename> and <filename>Release</filename> files
 399 to describe the packages available at that location. </para>
 400
 401 <para>The <filename>Packages</filename> file is normally found in the directory
 402 <filename>.../dists/<replaceable>dist-name</replaceable>/<replaceable>component</replaceable>/<replaceable>arch</replaceable></filename>:
 403 for example, <filename>.../dists/stable/main/binary-i386/Packages</filename>.
 404 It consists of a series of multi-line records, one for each package available
 405 in that directory.  Only two lines in each record are relevant for setting
 406 APT priorities:
 407 <variablelist>
 408 <varlistentry>
 409 <term>the <literal>Package:</literal> line</term>
 410 <listitem><simpara>gives the package name</simpara></listitem>
 411 </varlistentry>
 412 <varlistentry>
 413 <term>the <literal>Version:</literal> line</term>
 414 <listitem><simpara>gives the version number for the named package</simpara></listitem>
 415 </varlistentry>
 416 </variablelist>
 417 </para>
 418
 419 <para>The <filename>Release</filename> file is normally found in the directory
 420 <filename>.../dists/<replaceable>dist-name</replaceable></filename>:
 421 for example, <filename>.../dists/stable/Release</filename>,
 422 or <filename>.../dists/&stable-codename;/Release</filename>.
 423 It consists of a single multi-line record which applies to <emphasis>all</emphasis> of
 424 the packages in the directory tree below its parent.  Unlike the
 425 <filename>Packages</filename> file, nearly all of the lines in a <filename>Release</filename>
 426 file are relevant for setting APT priorities:
 427
 428 <variablelist>
 429 <varlistentry>
 430 <term>the <literal>Archive:</literal> or <literal>Suite:</literal> line</term>
 431 <listitem><simpara>names the archive to which all the packages
 432 in the directory tree belong.  For example, the line
 433 "Archive: stable" or
 434 "Suite: stable"
 435 specifies that all of the packages in the directory
 436 tree below the parent of the <filename>Release</filename> file are in a
 437 <literal>stable</literal> archive.  Specifying this value in the APT preferences file
 438 would require the line:
 439 </simpara>
 440 <programlisting>
 441 Pin: release a=stable
 442 </programlisting>
 443 </listitem>
 444 </varlistentry>
 445
 446 <varlistentry>
 447 <term>the <literal>Codename:</literal> line</term>
 448 <listitem><simpara>names the codename to which all the packages
 449 in the directory tree belong.  For example, the line
 450 "Codename: &testing-codename;"
 451 specifies that all of the packages in the directory
 452 tree below the parent of the <filename>Release</filename> file belong to a version named
 453 <literal>&testing-codename;</literal>.  Specifying this value in the APT preferences file
 454 would require the line:
 455 </simpara>
 456 <programlisting>
 457 Pin: release n=&testing-codename;
 458 </programlisting>
 459 </listitem>
 460 </varlistentry>
 461
 462 <varlistentry>
 463 <term>the <literal>Version:</literal> line</term>
 464 <listitem><simpara>names the release version.  For example, the
 465 packages in the tree might belong to Debian release
 466 version &stable-version;.  Note that there is normally no version number for the
 467 <literal>testing</literal> and <literal>unstable</literal> distributions because they
 468 have not been released yet.  Specifying this in the APT preferences
 469 file would require one of the following lines.
 470 </simpara>
 471
 472 <programlisting>
 473 Pin: release v=&stable-version;
 474 Pin: release a=stable, v=&stable-version;
 475 Pin: release &stable-version;
 476 </programlisting>
 477
 478 </listitem>
 479 </varlistentry>
 480
 481 <varlistentry>
 482 <term>the <literal>Component:</literal> line</term>
 483 <listitem><simpara>names the licensing component associated with the
 484 packages in the directory tree of the <filename>Release</filename> file.
 485 For example, the line "Component: main" specifies that
 486 all the packages in the directory tree are from the <literal>main</literal>
 487 component, which entails that they are licensed under terms listed
 488 in the Debian Free Software Guidelines.  Specifying this component
 489 in the APT preferences file would require the line:
 490 </simpara>
 491 <programlisting>
 492 Pin: release c=main
 493 </programlisting>
 494 </listitem>
 495 </varlistentry>
 496
 497 <varlistentry>
 498 <term>the <literal>Origin:</literal> line</term>
 499 <listitem><simpara>names the originator of the packages in the
 500 directory tree of the <filename>Release</filename> file.  Most commonly, this is
 501 <literal>Debian</literal>.  Specifying this origin in the APT preferences file
 502 would require the line:
 503 </simpara>
 504 <programlisting>
 505 Pin: release o=Debian
 506 </programlisting>
 507 </listitem>
 508 </varlistentry>
 509
 510 <varlistentry>
 511 <term>the <literal>Label:</literal> line</term>
 512 <listitem><simpara>names the label of the packages in the directory tree
 513 of the <filename>Release</filename> file.  Most commonly, this is
 514 <literal>Debian</literal>.  Specifying this label in the APT preferences file
 515 would require the line:
 516 </simpara>
 517 <programlisting>
 518 Pin: release l=Debian
 519 </programlisting>
 520 </listitem>
 521 </varlistentry>
 522 </variablelist>
 523 </para>
 524
 525 <para>All of the <filename>Packages</filename> and <filename>Release</filename>
 526 files retrieved from locations listed in the &sources-list; file are stored
 527 in the directory <filename>/var/lib/apt/lists</filename>, or in the file named
 528 by the variable <literal>Dir::State::Lists</literal> in the <filename>apt.conf</filename> file.
 529 For example, the file
 530 <filename>debian.lcs.mit.edu_debian_dists_unstable_contrib_binary-i386_Release</filename>
 531 contains the <filename>Release</filename> file retrieved from the site
 532 <literal>debian.lcs.mit.edu</literal> for <literal>binary-i386</literal> architecture
 533 files from the <literal>contrib</literal> component of the <literal>unstable</literal>
 534 distribution.</para>
 535 </refsect2>
 536
 537 <refsect2>
 538 <title>Optional Lines in an APT Preferences Record</title>
 539
 540 <para>Each record in the APT preferences file can optionally begin with
 541 one or more lines beginning with the word <literal>Explanation:</literal>.
 542 This provides a place for comments.</para>
 543 </refsect2>
 544 </refsect1>
 545
 546 <refsect1>
 547 <title>Examples</title>
 548 <refsect2>
 549 <title>Tracking Stable</title>
 550
 551 <para>The following APT preferences file will cause APT to assign a
 552 priority higher than the default (500) to all package versions belonging
 553 to a <literal>stable</literal> distribution and a prohibitively low priority to
 554 package versions belonging to other <literal>Debian</literal> distributions.
 555
 556 <programlisting>
 557 Explanation: Uninstall or do not install any Debian-originated
 558 Explanation: package versions other than those in the stable distro
 559 Package: *
 560 Pin: release a=stable
 561 Pin-Priority: 900
 562
 563 Package: *
 564 Pin: release o=Debian
 565 Pin-Priority: -10
 566 </programlisting>
 567 </para>
 568
 569 <para>With a suitable &sources-list; file and the above preferences file,
 570 any of the following commands will cause APT to upgrade to the
 571 latest <literal>stable</literal> version(s).
 572
 573 <programlisting>
 574 apt-get install <replaceable>package-name</replaceable>
 575 apt-get upgrade
 576 apt-get dist-upgrade
 577 </programlisting>
 578 </para>
 579
 580 <para>The following command will cause APT to upgrade the specified
 581 package to the latest version from the <literal>testing</literal> distribution;
 582 the package will not be upgraded again unless this command is given
 583 again.
 584
 585 <programlisting>
 586 apt-get install <replaceable>package</replaceable>/testing
 587 </programlisting>
 588 </para>
 589 </refsect2>
 590
 591  <refsect2>
 592  <title>Tracking Testing or Unstable</title>
 593
 594 <para>The following APT preferences file will cause APT to assign
 595 a high priority to package versions from the <literal>testing</literal>
 596 distribution, a lower priority to package versions from the
 597 <literal>unstable</literal> distribution, and a prohibitively low priority
 598 to package versions from other <literal>Debian</literal> distributions.
 599
 600 <programlisting>
 601 Package: *
 602 Pin: release a=testing
 603 Pin-Priority: 900
 604
 605 Package: *
 606 Pin: release a=unstable
 607 Pin-Priority: 800
 608
 609 Package: *
 610 Pin: release o=Debian
 611 Pin-Priority: -10
 612 </programlisting>
 613 </para>
 614
 615 <para>With a suitable &sources-list; file and the above preferences file,
 616 any of the following commands will cause APT to upgrade to the latest
 617 <literal>testing</literal> version(s).
 618
 619 <programlisting>
 620 apt-get install <replaceable>package-name</replaceable>
 621 apt-get upgrade
 622 apt-get dist-upgrade
 623 </programlisting>
 624 </para>
 625
 626 <para>The following command will cause APT to upgrade the specified
 627 package to the latest version from the <literal>unstable</literal> distribution.
 628 Thereafter, <command>apt-get upgrade</command> will upgrade
 629 the package to the most recent <literal>testing</literal> version if that is
 630 more recent than the installed version, otherwise, to the most recent
 631 <literal>unstable</literal> version if that is more recent than the installed
 632 version.
 633
 634 <programlisting>
 635 apt-get install <replaceable>package</replaceable>/unstable
 636 </programlisting>
 637 </para>
 638 </refsect2>
 639
 640
 641 <refsect2>
 642 <title>Tracking the evolution of a codename release</title>
 643
 644 <para>The following APT preferences file will cause APT to assign a
 645 priority higher than the default (500) to all package versions belonging
 646 to a specified codename of a distribution and a prohibitively low priority to
 647 package versions belonging to other <literal>Debian</literal> distributions,
 648 codenames and archives.
 649 Note that with this APT preference APT will follow the migration of a release
 650 from the archive <literal>testing</literal> to <literal>stable</literal> and
 651 later <literal>oldstable</literal>. If you want to follow for example the progress
 652 in <literal>testing</literal> notwithstanding the codename changes you should use
 653 the example configurations above.
 654
 655 <programlisting>
 656 Explanation: Uninstall or do not install any Debian-originated package versions
 657 Explanation: other than those in the distribution codenamed with &testing-codename; or sid
 658 Package: *
 659 Pin: release n=&testing-codename;
 660 Pin-Priority: 900
 661
 662 Explanation: Debian unstable is always codenamed with sid
 663 Package: *
 664 Pin: release n=sid
 665 Pin-Priority: 800
 666
 667 Package: *
 668 Pin: release o=Debian
 669 Pin-Priority: -10
 670 </programlisting>
 671 </para>
 672
 673 <para>With a suitable &sources-list; file and the above preferences file,
 674 any of the following commands will cause APT to upgrade to the
 675 latest version(s) in the release codenamed with <literal>&testing-codename;</literal>.
 676
 677 <programlisting>
 678 apt-get install <replaceable>package-name</replaceable>
 679 apt-get upgrade
 680 apt-get dist-upgrade
 681 </programlisting>
 682 </para>
 683
 684 <para>The following command will cause APT to upgrade the specified
 685 package to the latest version from the <literal>sid</literal> distribution.
 686 Thereafter, <command>apt-get upgrade</command> will upgrade
 687 the package to the most recent <literal>&testing-codename;</literal> version if that is
 688 more recent than the installed version, otherwise, to the most recent
 689 <literal>sid</literal> version if that is more recent than the installed
 690 version.
 691
 692 <programlisting>
 693 apt-get install <replaceable>package</replaceable>/sid
 694 </programlisting>
 695 </para>
 696 </refsect2>
 697 </refsect1>
 698
 699 <refsect1>
 700 <title>Files</title>
 701   <variablelist>
 702     &file-preferences;
 703   </variablelist>
 704 </refsect1>
 705
 706 <refsect1>
 707 <title>See Also</title>
 708 <para>&apt-get; &apt-cache; &apt-conf; &sources-list;
 709 </para>
 710 </refsect1>
 711
 712  &manbugs;
 713
 714 </refentry>