apt_preferences man page 20030316
OK, gang, here is my update to the apt_preferences.5 man page.
I have tried to address the issues raised by Jason earlier
(quotation below) and to the problems I mentioned in my last
message (also quoted below). The sgml diff is attached.
--
Thomas Hood
APT_PREFERENCES(5) APT_PREFERENCES(5)
NAME
apt_preferences - Preference control file for APT
DESCRIPTION
The APT preferences file /etc/apt/preferences can be used
to control which versions of packages will be selected for
installation.
Several versions of a package may be available for instal
lation when the sources.list(5) file contains references
to more than one distribution (for example, stable and
testing). APT assigns a priority to each version that is
available. Subject to dependency constraints, apt-get
selects the version with the highest priority for instal
lation. The APT preferences file overrides the priorities
that APT assigns to package versions by default, thus giv
ing the user control over which one is selected for
installation.
Several instances of the same version of a package may be
available when the sources.list(5) file contains refer
ences to more than one source. In this case apt-get down
loads the instance listed earliest in the sources.list(5)
file. The APT preferences file does not affect the choice
of instance.
APT'S DEFAULT PRIORITY ASSIGNMENTS
If there is no preferences file or if there is no entry in
the file that applies to a particular version then the
priority assigned to that version is the priority of the
distribution to which that version belongs. It is possi
ble to single out a distribution, "the target release",
which receives a higher priority than other distributions
do by default. The target release can be set on the apt-
get command line or in the APT configuration file
/etc/apt/apt.conf. For example,
apt-get install -t testing some-package
APT::Default-Release "stable";
If the target release has been specified then APT uses the
following algorithm to set the priorities of the versions
of a package. Assign:
priority 100
to the version that is already installed (if any).
priority 500
to the versions that are not installed and do not
belong to the target release.
priority 990
to the versions that are not installed and belong
to the target release.
If the target release has not been specified then APT sim
ply assigns priority 100 to all installed package versions
and priority 500 to all uninstalled package versions.
APT then applies the following rules, listed in order of
precedence, to determine which version of a package to
install.
· Never downgrade unless the priority of an available ver
sion exceeds 1000. ("Downgrading" is installing a less
recent version of a package in place of a more recent
version. Note that none of APT's default priorities
exceeds 1000; such high priorities can only be set in
the preferences file. Note also that downgrading a
package can be risky.)
· Install the highest priority version.
· If two or more versions have the same priority, install
the most recent one (that is, the one with the higher
version number).
· If two or more versions have the same priority and ver
sion number but either the packages differ in some of
their metadata or the --reinstall option is given,
install the uninstalled one.
In a typical situation, the installed version of a package
(priority 100) is not as recent as one of the versions
available from the sources listed in the sources.list(5)
file (priority 500 or 990). Then the package will be
upgraded when apt-get install some-package or apt-get
upgrade is executed.
More rarely, the installed version of a package is more
recent than any of the other available versions. The
package will not be downgraded when apt-get install some-
package or apt-get upgrade is executed.
Sometimes the installed version of a package is more
recent than the version belonging to the target release,
but not as recent as a version belonging to some other
distribution. Such a package will indeed be upgraded when
apt-get install some-package or apt-get upgrade is exe
cuted, because at least one of the available versions has
a higher priority than the installed version.
THE EFFECT OF APT PREFERENCES
The APT preferences file allows the system administrator
to control the assignment of priorities. The file con
sists of one or more multi-line records separated by blank
lines. Records can have one of two forms, a specific form
and a general form.
· The specific form assigns a priority (a "Pin-Priority")
to a specified package and specified version or version
range. For example, the following record assigns a high
priority to all versions of the perl package whose ver
sion number begins with "5.8".
Package: perl
Pin: version 5.8*
Pin-Priority: 1001
· The general form assigns a priority to all of the pack
age versions in a given distribution (that is, to all
the versions of packages that are listed in a certain
Release file) or to all of the package versions coming
from a particular Internet site, as identified by the
site's fully qualified domain name.
This general-form entry in the APT preferences file
applies only to groups of packages. For example, the
following record assigns a high priority to all package
versions available from the local site.
Package: *
Pin: origin ""
Pin-Priority: 999
A note of caution: the keyword used here is "origin".
This should not be confused with the Origin of a distri
bution as specified in a Release file. What follows the
"Origin:" tag in a Release file is not an Internet
address but an author or vendor name, such as "Debian"
or "Ximian".
The following record assigns a low priority to all pack
age versions belonging to any distribution whose Archive
name is "unstable".
Package: *
Pin: release a=unstable
Pin-Priority: 50
The following record assigns a high priority to all
package versions belonging to any release whose Archive
name is "stable" and whose release Version number is
"3.0".
Package: *
Pin: release a=unstable, v=3.0
Pin-Priority: 50
HOW APT INTERPRETS PRIORITIES
Priorities (P) assigned in the APT preferences file must
be positive or negative integers. They are interpreted as
follows (roughly speaking):
P > 1000
causes a version to be installed even if this con
stitutes a downgrade of the package
990 < P <=1000
causes a version to be installed even if it does
not come from the target release, unless the
installed version is more recent
500 < P <=990
causes a version to be installed unless there is a
version available belonging to the target release
or the installed version is more recent
100 < P <=500
causes a version to be installed unless there is a
version available belonging to some other distribu
tion or the installed version is more recent
0 <= P <=100
causes a version to be installed only if there is
no installed version of the package
P < 0 prevents the version from being installed
If any specific-form records match an available package
version then the first such record determines the priority
of the package version. Failing that, if any general-form
records match an available package version then the first
such record determines the priority of the package ver
sion.
For example, suppose the APT preferences file contains the
three records presented earlier:
Package: perl
Pin: version 5.8*
Pin-Priority: 1001
Package: *
Pin: origin ""
Pin-Priority: 999
Package: *
Pin: release unstable
Pin-Priority: 50
Then:
· The most recent available version of the perl package
will be installed, so long as that version's version
number begins with "5.8". If any 5.8* version of perl
is available and the installed version is 5.9*, then
perl will be downgraded.
· A version of any package other than perl that is avail
able from the local system has priority over other ver
sions, even versions belonging to the target release.
· A version of a package whose origin is not the local
system but some other site listed in sources.list(5) and
which belongs to an unstable distribution is only
installed if it is selected for installation and no ver
sion of the package is already installed.
DETERMINATION OF PACKAGE VERSION AND DISTRIBUTION PROPERTIES
The locations listed in the sources.list(5) file should
provide Packages and Release files to describe the pack
ages available at that location.
The Packages file is normally found in the directory for
example, .../dists/stable/main/binary-i386/Packages. It
consists of a series of multi-line records, one for each
package available in that directory. Only two lines in
each record are relevant for setting APT priorities:
the Package: line
gives the package name
the Version: line
gives the version number for the named package
The Release file is normally found in the directory for
example, .../dists/stable/Release, or
.../dists/woody/Release. It consists of a single multi-
line record which applies to all of the packages in the
directory tree below its parent. Unlike the Packages
file, nearly all of the lines in a Release file are rele
vant for setting APT priorities:
the Archive: line
names the archive to which all the packages in the
directory tree belong. For example, the line
"Archive: stable" specifies that all of the pack
ages in the directory tree below the parent of the
Release file are in a stable archive. Specifying
this value in the APT preferences file would
require the line:
Pin: release a=stable
the Version: line
names the release version. For example, the pack
ages in the tree might belong to Debian GNU/Linux
release version 3.0. Note that there is normally
no version number for the testing and unstable dis
tributions because they have not been released yet.
Specifying this in the APT preferences file would
require one of the following lines.
Pin: release v=3.0
Pin: release a=stable v=3.0
Pin: release 3.0
the Component: line
names the licensing component associated with the
packages in the directory tree of the Release file.
For example, the line "Component: main" specifies
that all the packages in the directory tree are
from the main component, which entails that they
are licensed under terms listed in the Debian Free
Software Guidelines. Specifying this component in
the APT preferences file would require the line:
Pin: release c=main
the Origin: line
names the originator of the packages in the direc
tory tree of the Release file. Most commonly, this
is Debian. Specifying this origin in the APT pref
erences file would require the line:
Pin: release o=Debian
the Label: line
names the label of the packages in the directory
tree of the Release file. Most commonly, this is
Debian. Specifying this label in the APT prefer
ences file would require the line:
Pin: release l=Debian
All of the Packages and Release files retrieved from loca
tions listed in the sources.list(5) file are stored in the
directory /var/lib/apt/lists, or in the file named by the
variable Dir::State::Lists in the apt.conf file. For
example, the file debian.lcs.mit.edu_debian_dists_unsta
ble_contrib_binary-i386_Release contains the Release file
retrieved from the site debian.lcs.mit.edu for binary-i386
architecture files from the contrib component of the
unstable distribution.
OPTIONAL LINES IN AN APT PREFERENCES RECORD
Each record in the APT preferences file can optionally
begin with one or more lines beginning with the word
Explanation:. This provides a place for comments.
The Pin-Priority: line in each APT preferences record is
optional. If omitted, APT assigs a priority of 1 less
than the last value specified on a line beginning with
Pin-Priority: release ....
EXAMPLES
TRACKING STABLE
The following APT preferences file will cause APT to
assign a priority higher than the default (500) to all
package versions belonging to a stable distribution and a
prohibitively low priority to package versions belonging
to other Debian distributions.
Explanation: Uninstall or do not install any Debian-originated
Explanation: package versions other than those in the stable
distro
Package: *
Pin: release a=stable
Pin-Priority: 900
Package: *
Pin: release o=Debian
Pin-Priority: -10
With a suitable sources.list(5) file and the above prefer
ences file, any of the following commands will cause APT
to upgrade to the latest stable version(s).
apt-get install package-name
apt-get upgrade
apt-get dist-upgrade
The following command will cause APT to upgrade the speci
fied package to the latest version from the testing dis
tribution; the package will not be upgraded again unless
this command is given again.
apt-get install package/testing
TRACKING TESTING OR UNSTABLE
The following APT preferences file will cause APT to
assign a high priority to package versions from the test
ing distribution, a lower priority to package versions
from the unstable distribution, and a prohibitively low
priority to package versions from other Debian distribu
tions.
Package: *
Pin: release a=testing
Pin-Priority: 900
Package: *
Pin: release a=unstable
Pin-Priority: 800
Package: *
Pin: release o=Debian
Pin-Priority: -10
With a suitable sources.list(5) file and the above prefer
ences file, any of the following commands will cause APT
to upgrade to the latest testing version(s).
apt-get install package-name
apt-get upgrade
apt-get dist-upgrade
The following command will cause APT to upgrade the speci
fied package to the latest version from the unstable dis
tribution. Thereafter, apt-get upgrade will upgrade the
package to the most recent testing version if that is more
recent than the installed version, otherwise, to the most
recent unstable version if that is more recent than the
installed version.
apt-get install package/unstable
SEE ALSO
apt-get(8) apt-cache(8) apt.conf(5) sources.list(5)
BUGS
See the APT bug page <URL:http://bugs.debian.org/apt>. If
you wish to report a bug in APT, please see
/usr/share/doc/debian/bug-reporting.txt or the report
bug(1) command.
AUTHOR
APT was written by the APT team <apt@packages.debian.org>.
16 March 2003 APT_PREFERENCES(5)
On Mon, 2003-01-06 at 02:33, Jason Gunthorpe wrote:
> Looks OK..
>
> The first paragraph: '<para>Several versions of a package' has a bit of a
> misleading slant, it's actually possible that a single source can have
> multiple version of the package, and that multiple download sites can
> exist if the same version of a package is in more than one of
> stable,testing,unstable. I occasionaly get confused people mailing me that
> APT is dowloading (and thus, they thing it must be using) a package from
> unstable, when in fact unstable and testing have the same version for this
> package.
>
> The latter part might be clarified slightly with an example from
> 'apt-cache policy foo' which summarizes all the output into two essential
> lines, the 'Installed:' line and the 'Candidate:' line. Subject to
> dependency constraints and user selection APT will select one of the two
> for installation. I also occasonally get messages from people who are
> trying to all-downgrade and don't understand that it is a legitimate
> position for APT to 'do nothing' to a package.
>
> Moving on, '# Command to install the <literal/testing/ version' .. I also
> get many confused emails about this. -t testing does not *force* testing
> to be selected. It means that if upgrading from a version <= testing
> select testing, otherwise select the highest available version.
> The rest of the document gets that right, but it's probably best to push
> the point at the very first time the concept is introduced. The 'Tracking
> Testing' section at the bottom is a great addition. You might want to note
> that 'apt-get -t unstable install foo' will still correctly override the
> preferences file and install those packages from unstable.
>
> A note should be added that downgrading packages technically isn't
> supported by the debian project and should be used sparingly.
>
> It may also be worth noting that if two instances have the same version
> number they can still be considered to be different if their dependency
> lines, installed-size, etc do not match exactly. In this instance APT
> always prefers to reinstall the package. This comes up commonly if people
> recompile something but do not change the version number.
>
> Have the examples been checked by using apt-cache policy? I"m not sure the
> last very complex one is right. I'm also not entirely use the description
> of the version'd pin's matches what the code does, though your description
> perhaps describes what it should do.
>
> Any reference to a verson number in a release (ie v=3.0) should probably
> be considered to be v=3.0*. This is because we now have a release 3.0r1
> which doesn't exactly match 3.0 (and yes, this is kind of unfortunate) :|
>
> There is a document called 'files.sgml' in the APT source tree which gives
> a description of the release file format. It might help clarify some of
> the description of that format.
>
> Jason
I wrote:
> APT assigns priorities to versions,
> not to instances; it does not keep track of instances until
> it needs to find an instance of a selected version to download
> for installation.
>
> Additionally:
> 1. Use "distribution" more consistently rather than "release"
> 2. Clarify some of the wording
> 3. Say "upgrade" instead of "dist-upgrade"
--- apt_preferences.5.sgml_ORIG Fri Jan 31 05:39:11 2003
+++ apt_preferences.5.sgml Sun Mar 16 17:05:52 2003
@@ -20,138 +20,138 @@
<refpurpose>Preference control file for APT</>
</refnamediv>
-<RefSect1><Title>Description</>
+<RefSect1>
+<Title>Description</Title>
<para>
The APT preferences file <filename>/etc/apt/preferences</>
-can be used to control which version of a package will be selected
+can be used to control which versions of packages will be selected
for installation.
</para>
-<para>Several versions of a package may be available for installation when
+<para>
+Several versions of a package may be available for installation when
the &sources-list; file contains references to more than one distribution
-(for example, <literal>stable</literal> and <literal>testing</literal>);
-furthermore, several instances of the same version of a package may be
-available when the file contains references to more than one download site
-for a particular distribution. APT assigns a "priority" to each instance
-that is available. (In what follows, an "instance" will be an instance of
-a package that is available according to &sources-list;.)
-Subject to dependency constraints, <command>apt-get</command> installs the
-instance with the highest priority. If two instances have the same
-priority then it installs the more recent one, that is, the one with the
-higher version number.
-</para>
-
-<para>The APT preferences file overrides the priorities that APT assigns
-to package instances by default, thus giving the user control over which
+(for example, <literal>stable</literal> and <literal>testing</literal>).
+APT assigns a priority to each version that is available.
+Subject to dependency constraints, <command>apt-get</command> selects the
+version with the highest priority for installation.
+The APT preferences file overrides the priorities that APT assigns to
+package versions by default, thus giving the user control over which
one is selected for installation.
</para>
+<para>
+Several instances of the same version of a package may be available when
+the &sources-list; file contains references to more than one source.
+In this case <command>apt-get</command> downloads the instance listed
+earliest in the &sources-list; file.
+The APT preferences file does not affect the choice of instance.
+</para>
<RefSect2><Title>APT's Default Priority Assignments</>
-<para>If there is no preferences file, or if there is no entry in the file
-that applies to a particular instance, then the priority assigned to that
-instance is the priority of the distribution to which that instance
-belongs. It is possible to single out a distribution, called the
-"target release", which receives a higher priority than other distributions.
+<para>
+If there is no preferences file or if there is no entry in the file
+that applies to a particular version then the priority assigned to that
+version is the priority of the distribution to which that version
+belongs. It is possible to single out a distribution, "the target release",
+which receives a higher priority than other distributions do by default.
The target release can be set on the <command>apt-get</command> command
line or in the APT configuration file <filename>/etc/apt/apt.conf</filename>.
For example,
-
<programlisting>
-# Command to install the <literal/testing/ version of <replaceable>some-package</replaceable>
<command>apt-get install -t testing <replaceable>some-package</replaceable></command>
</programlisting>
-
<programlisting>
-# Configuration setting to make <literal/stable/ the target release
APT::Default-Release "stable";
</programlisting>
</para>
-<para>If a target release has been specified then APT uses the following
-algorithm to set the priorities of the instances of a package. Assign:
-
+<para>
+If the target release has been specified then APT uses the following
+algorithm to set the priorities of the versions of a package. Assign:
<variablelist>
<varlistentry>
<term>priority 100</term>
-<listitem><simpara>to the instance that is already installed (if any).
-</simpara></listitem>
+<listitem><simpara>to the version that is already installed (if any).</simpara></listitem>
</varlistentry>
<varlistentry>
<term>priority 500</term>
-<listitem><simpara>to the instances that are not installed
-and do not belong to the target release.
-</simpara></listitem>
+<listitem><simpara>to the versions that are not installed and do not belong to the target release.</simpara></listitem>
</varlistentry>
<varlistentry>
<term>priority 990</term>
-<listitem><simpara>to the instances that are not installed
-and belong to the target release.
-</simpara></listitem>
+<listitem><simpara>to the versions that are not installed and belong to the target release.</simpara></listitem>
</varlistentry>
</variablelist>
</para>
-<para>If no target release has been specified then APT simply assigns
-priority 100 to all installed package instances and priority 500 to all
-uninstalled package instances.
+<para>
+If the target release has not been specified then APT simply assigns
+priority 100 to all installed package versions and priority 500 to all
+uninstalled package versions.
</para>
-<para>APT then applies the following rules, listed in order of precedence,
-to determine which instance of a package to install.
-
+<para>
+APT then applies the following rules, listed in order of precedence,
+to determine which version of a package to install.
<itemizedlist>
-<listitem><simpara>Never downgrade unless the priority of an available instance
-exceeds 1000. ("Downgrading" is installing a less recent version of a package
-in place of a more recent version. Note that none of APT's default priorities
-exceeds 1000; such high priorities can only be set in the preferences file.)
-</simpara></listitem>
-<listitem><simpara>Install the highest priority instance.
-</simpara></listitem>
-<listitem><simpara>If two or more instances have the same priority,
-install the most recent one.
-</simpara></listitem>
-<listitem><simpara>If two or more instances have the same version number,
-install the one whose source is listed earliest in &sources-list;.
-(The installed instance, if there is one, is always preferred in such a
-comparison unless <command>apt-get --reinstall</command> is used.)
-</simpara></listitem>
+<listitem><simpara>Never downgrade unless the priority of an available
+version exceeds 1000. ("Downgrading" is installing a less recent version
+of a package in place of a more recent version. Note that none of APT's
+default priorities exceeds 1000; such high priorities can only be set in
+the preferences file. Note also that downgrading a package
+can be risky.)</simpara></listitem>
+<listitem><simpara>Install the highest priority version.</simpara></listitem>
+<listitem><simpara>If two or more versions have the same priority,
+install the most recent one (that is, the one with the higher version
+number).</simpara></listitem>
+<listitem><simpara>If two or more versions have the same priority and
+version number but either the packages differ in some of their metadata or the
+<literal/--reinstall/ option is given, install the uninstalled one.</simpara></listitem>
</itemizedlist>
</para>
-<para>In a typical situation, the installed instance of a package (priority 100)
-is not as recent as one of the instances available from the sources listed in
-the &sources-list; file (priority 500 or 990). Then the package will be
-upgraded with the command:
-<command>apt-get install</command> or <command>apt-get dist-upgrade</command>.
+<para>
+In a typical situation, the installed version of a package (priority 100)
+is not as recent as one of the versions available from the sources listed in
+the &sources-list; file (priority 500 or 990). Then the package will be upgraded
+when <command>apt-get install <replaceable>some-package</replaceable></command>
+or <command>apt-get upgrade</command> is executed.
</para>
-<para>Rarely, the installed instance of a package is <emphasis/more/ recent
-than any of the other available instances. The package will not be downgraded.
+<para>
+More rarely, the installed version of a package is <emphasis/more/ recent
+than any of the other available versions. The package will not be downgraded
+when <command>apt-get install <replaceable>some-package</replaceable></command>
+or <command>apt-get upgrade</command> is executed.
</para>
-<para>Sometimes the installed instance of a package is more recent than the
+<para>
+Sometimes the installed version of a package is more recent than the
version belonging to the target release, but not as recent as a version
-belonging to some other distribution. Such a package will indeed be upgraded,
-because at least <emphasis/one/ of the available instances has a higher
-priority than the installed instance.
+belonging to some other distribution. Such a package will indeed be upgraded
+when <command>apt-get install <replaceable>some-package</replaceable></command>
+or <command>apt-get upgrade</command> is executed,
+because at least <emphasis/one/ of the available versions has a higher
+priority than the installed version.
</para>
</RefSect2>
<RefSect2><Title>The Effect of APT Preferences</>
-<para>The APT preferences file allows the system administrator to customize
-priorities. The file consists of one or more multi-line records separated
-by blank lines. Records can have one of two forms, a specific form and a
-general form.
+<para>
+The APT preferences file allows the system administrator to control the
+assignment of priorities. The file consists of one or more multi-line records
+separated by blank lines. Records can have one of two forms, a specific form
+and a general form.
<itemizedlist>
<listitem>
-<simpara>The "specific" form pins a priority (a "Pin-Priority") to a
-specified package and specified version or version range. For
-example, the following record pins a high priority to all versions of
-the <filename/perl/ package whose version number begins with
-"<literal/5.8/".
+<simpara>
+The specific form assigns a priority (a "Pin-Priority") to a
+specified package and specified version or version range. For example,
+the following record assigns a high priority to all versions of
+the <filename/perl/ package whose version number begins with "<literal/5.8/".
</simpara>
<programlisting>
@@ -162,17 +162,17 @@
</listitem>
<listitem><simpara>
-The "general" form pins a priority to all of the package versions in a
+The general form assigns a priority to all of the package versions in a
given distribution (that is, to all the versions of packages that are
-listed in a certain <filename/Release/ file), or to all of the package
-instances coming from a particular Internet site, as identified by its
-fully qualified domain name.
+listed in a certain <filename/Release/ file) or to all of the package
+versions coming from a particular Internet site, as identified by the
+site's fully qualified domain name.
</simpara>
-<simpara>This general-form entry in the APT preferences file applies only
-to groups of packages. For example, the following record causes APT to
-assign a high priority to all package instances available from the local
-site.
+<simpara>
+This general-form entry in the APT preferences file applies only
+to groups of packages. For example, the following record assigns a high
+priority to all package versions available from the local site.
</simpara>
<programlisting>
@@ -181,16 +181,17 @@
Pin-Priority: 999
</programlisting>
-<simpara>A note of caution: the keyword used here is "<literal/origin/".
-This should not be confused with the "Origin:" of a distribution as
+<simpara>
+A note of caution: the keyword used here is "<literal/origin/".
+This should not be confused with the Origin of a distribution as
specified in a <filename/Release/ file. What follows the "Origin:" tag
-in a <filename/Release/ file is usually not an Internet site address
+in a <filename/Release/ file is not an Internet address
but an author or vendor name, such as "Debian" or "Ximian".
</simpara>
-<simpara>The following record causes APT to assign a low priority to all
-package versions belonging to any distribution whose "Archive"
-(<literal/a/) name is "<literal/unstable/".
+<simpara>
+The following record assigns a low priority to all package versions
+belonging to any distribution whose Archive name is "<literal/unstable/".
</simpara>
<programlisting>
@@ -199,10 +200,10 @@
Pin-Priority: 50
</programlisting>
-<simpara>The following record causes APT to assign a high priority to all
-package versions belonging to any release whose "Archive" (<literal/a/)
-name is "<literal/stable/" and whose release "Version" (<literal/v/)
-number is "<literal/3.0/".
+<simpara>
+The following record assigns a high priority to all package versions
+belonging to any release whose Archive name is "<literal/stable/"
+and whose release Version number is "<literal/3.0/".
</simpara>
<programlisting>
@@ -216,55 +217,58 @@
</RefSect2>
-<RefSect2><Title>How APT Interprets Priorities</Title>
+<RefSect2>
+<Title>How APT Interprets Priorities</Title>
-<para>Priorities (P) assigned in the APT preferences file must be positive
+<para>
+Priorities (P) assigned in the APT preferences file must be positive
or negative integers. They are interpreted as follows (roughly speaking):
<variablelist>
-<varlistentry><term>P > 1000</term>
-<listitem><simpara>causes an instance to be installed
-even if this constitutes a downgrade of the package
-</simpara></listitem>
+<varlistentry>
+<term>P > 1000</term>
+<listitem><simpara>causes a version to be installed even if this
+constitutes a downgrade of the package</simpara></listitem>
</varlistentry>
-<varlistentry><term>990 < P <=1000</term>
-<listitem><simpara>causes an instance to be installed
+<varlistentry>
+<term>990 < P <=1000</term>
+<listitem><simpara>causes a version to be installed
even if it does not come from the target release,
-unless the installed instance is more recent
-</simpara></listitem>
+unless the installed version is more recent</simpara></listitem>
</varlistentry>
-<varlistentry><term>500 < P <=990</term>
-<listitem><simpara>causes an instance to be installed
-unless there is an instance available belonging to the target release
-or the installed version is more recent
-</simpara></listitem>
+<varlistentry>
+<term>500 < P <=990</term>
+<listitem><simpara>causes a version to be installed
+unless there is a version available belonging to the target release
+or the installed version is more recent</simpara></listitem>
</varlistentry>
-<varlistentry><term>100 < P <=500</term>
-<listitem><simpara>causes an instance to be installed
-unless there is an instance available belonging to some other
-distribution or the installed version is more recent
-</simpara></listitem>
-<varlistentry><term>0 <= P <=100</term>
-<listitem><simpara>causes an instance to be installed
-only if there is no installed instance of the package
-</simpara></listitem>
+<varlistentry>
+<term>100 < P <=500</term>
+<listitem><simpara>causes a version to be installed
+unless there is a version available belonging to some other
+distribution or the installed version is more recent</simpara></listitem>
+<varlistentry>
+<term>0 <= P <=100</term>
+<listitem><simpara>causes a version to be installed
+only if there is no installed version of the package</simpara></listitem>
</varlistentry>
-<varlistentry><term>P < 0</term>
-<listitem><simpara>prevents the instance from being installed
-</simpara></listitem>
+<varlistentry>
+<term>P < 0</term>
+<listitem><simpara>prevents the version from being installed</simpara></listitem>
</varlistentry>
</variablelist>
</para>
-<para>If one of the specific-form records described above matches an
-available package instance, then that record determines the priority of
-the instance. If two specific-form records match an available instance,
-then the first record encountered determines the priority. If two
-general-form records match an available instance, then the first record
-encountered determines the priority.
+<para>
+If any specific-form records match an available package version then the
+first such record determines the priority of the package version.
+Failing that,
+if any general-form records match an available package version then the
+first such record determines the priority of the package version.
</para>
-<para>For example, suppose the APT preferences file contains the three
+<para>
+For example, suppose the APT preferences file contains the three
records presented earlier:
<programlisting>
@@ -289,27 +293,30 @@
with "<literal/5.8/". If <emphasis/any/ 5.8* version of <literal/perl/ is
available and the installed version is 5.9*, then <literal/perl/ will be
downgraded.</simpara></listitem>
-<listitem><simpara>An instance of any package other than <literal/perl/
-that is available from the local system has priority over other instances,
-even instances belonging to the target release.
-</simpara></listitem>
-<listitem><simpara>An instance of a package whose origin is not the local
-system but some other site listed in &sources-list;, and which belongs to
-an "<literal/unstable/" distribution, is only installed if it is selected
-for installation and no instance of the package is already installed.
+<listitem><simpara>A version of any package other than <literal/perl/
+that is available from the local system has priority over other versions,
+even versions belonging to the target release.
+</simpara></listitem>
+<listitem><simpara>A version of a package whose origin is not the local
+system but some other site listed in &sources-list; and which belongs to
+an <literal/unstable/ distribution is only installed if it is selected
+for installation and no version of the package is already installed.
</simpara></listitem>
</itemizedlist>
</para>
</RefSect2>
-<RefSect2><Title>Determination of Package Version and Distribution Properties</Title>
+<RefSect2>
+<Title>Determination of Package Version and Distribution Properties</Title>
-<para>The locations listed in a system's &sources-list; file should provide
+<para>
+The locations listed in the &sources-list; file should provide
<filename>Packages</filename> and <filename>Release</filename> files
-to describe the package instances available at that location.
+to describe the packages available at that location.
</para>
-<para>The <filename>Packages</filename> file is normally found in the directory
+<para>
+The <filename>Packages</filename> file is normally found in the directory
<filename>.../dists/<replaceable>dist-name</replaceable>/<replaceable>component</replaceable>/<replaceable>arch</replaceable></filename>:
for example, <filename>.../dists/stable/main/binary-i386/Packages</filename>.
It consists of a series of multi-line records, one for each package available
@@ -327,26 +334,27 @@
</variablelist>
</para>
-<para>The <filename>Release</filename> file is normally found in the directory
+<para>
+The <filename>Release</filename> file is normally found in the directory
<filename>.../dists/<replaceable>dist-name</replaceable></filename>:
for example, <filename>.../dists/stable/Release</filename>,
or <filename>.../dists/woody/Release</filename>.
It consists of a single multi-line record which applies to <emphasis/all/ of
-the package instances in the directory tree below its parent. Unlike the
+the packages in the directory tree below its parent. Unlike the
<filename/Packages/ file, nearly all of the lines in a <filename/Release/
file are relevant for setting APT priorities:
<variablelist>
<varlistentry>
<term>the <literal/Archive:/ line</term>
-<listitem><simpara>names the archive to which all the package instances
+<listitem><simpara>names the archive to which all the packages
in the directory tree belong. For example, the line
-<literal/Archive: stable/ specifies that all of the packages in the directory
-tree below the parent of the <filename/Release/ file are in the
+"Archive: stable"
+specifies that all of the packages in the directory
+tree below the parent of the <filename/Release/ file are in a
<literal/stable/ archive. Specifying this value in the APT preferences file
would require the line:
</simpara>
-
<programlisting>
Pin: release a=stable
</programlisting>
@@ -356,11 +364,11 @@
<varlistentry>
<term>the <literal/Version:/ line</term>
<listitem><simpara>names the release version. For example, the
-package instances in the tree might belong to Debian GNU/Linux release
-version 3.0. There is normally no version number for the "testing" and
-"unstable" distributions because they have not yet been released.
-Specifying this in the APT preferences file would require one of the
-following lines.
+packages in the tree might belong to Debian GNU/Linux release
+version 3.0. Note that there is normally no version number for the
+<literal/testing/ and <literal/unstable/ distributions because they
+have not been released yet. Specifying this in the APT preferences
+file would require one of the following lines.
</simpara>
<programlisting>
@@ -375,14 +383,13 @@
<varlistentry>
<term>the <literal/Component:/ line</term>
<listitem><simpara>names the licensing component associated with the
-package instances in the directory tree of the <filename/Release/
-file. For example, the line <literal/Component: main/ specifies that
-all the instances in the directory tree are from the <literal/main/
-component, meaning that they are licensed under terms listed in the
-Debian Free Software Guidelines. Specifying this component in the
-APT preferences file would require the line:
+packages in the directory tree of the <filename/Release/ file.
+For example, the line "Component: main" specifies that
+all the packages in the directory tree are from the <literal/main/
+component, which entails that they are licensed under terms listed
+in the Debian Free Software Guidelines. Specifying this component
+in the APT preferences file would require the line:
</simpara>
-
<programlisting>
Pin: release c=main
</programlisting>
@@ -391,12 +398,11 @@
<varlistentry>
<term>the <literal/Origin:/ line</term>
-<listitem><simpara>names the producer of the package instances in the
+<listitem><simpara>names the originator of the packages in the
directory tree of the <filename/Release/ file. Most commonly, this is
<literal/Debian/. Specifying this origin in the APT preferences file
would require the line:
</simpara>
-
<programlisting>
Pin: release o=Debian
</programlisting>
@@ -405,11 +411,11 @@
<varlistentry>
<term>the <literal/Label:/ line</term>
-<listitem><simpara>seems redundant. Most commonly, this is
+<listitem><simpara>names the label of the packages in the directory tree
+of the <filename/Release/ file. Most commonly, this is
<literal/Debian/. Specifying this label in the APT preferences file
would require the line:
</simpara>
-
<programlisting>
Pin: release l=Debian
</programlisting>
@@ -418,8 +424,9 @@
</variablelist>
</para>
-<para>All of the <filename>Packages</filename> and <filename>Release</filename>
-files retrieved from locations listed in the &sources-list; file are kept
+<para>
+All of the <filename>Packages</filename> and <filename>Release</filename>
+files retrieved from locations listed in the &sources-list; file are stored
in the directory <filename>/var/lib/apt/lists</filename>, or in the file named
by the variable <literal/Dir::State::Lists/ in the <filename/apt.conf/ file.
For example, the file
@@ -432,35 +439,41 @@
</RefSect2>
-<RefSect2><Title>Optional Lines in an APT Preferences Record</Title>
+<RefSect2>
+<Title>Optional Lines in an APT Preferences Record</Title>
-<para>Each record in the APT preferences file can optionally begin with
+<para>
+Each record in the APT preferences file can optionally begin with
one or more lines beginning with the word <literal/Explanation:/.
-This provides an opportunity to comment on the record.
+This provides a place for comments.
</para>
-<para>The <literal/Pin-Priority:/ line in each APT preferences record is
+<para>
+The <literal/Pin-Priority:/ line in each APT preferences record is
optional. If omitted, APT assigs a priority of 1 less than the last value
specified on a line beginning with <literal/Pin-Priority: release .../.
</para>
</RefSect2>
</RefSect1>
-<RefSect1><Title>Examples</>
-<RefSect2><Title>Tracking Stable</Title>
+<RefSect1>
+<Title>Examples</Title>
+<RefSect2>
+<Title>Tracking Stable</Title>
-<para>The following APT preferences file will cause APT to assign a
+<para>
+The following APT preferences file will cause APT to assign a
priority higher than the default (500) to all package versions belonging
to a <literal/stable/ distribution and a prohibitively low priority to
package versions belonging to other <literal/Debian/ distributions.
<programlisting>
+Explanation: Uninstall or do not install any Debian-originated
+Explanation: package versions other than those in the stable distro
Package: *
Pin: release a=stable
Pin-Priority: 900
-Explanation: Uninstall or do not install any Debian-originated
-Explanation: instances other than those in the stable distro
Package: *
Pin: release o=Debian
Pin-Priority: -10
@@ -479,20 +492,24 @@
</programlisting>
</para>
-<para>The following command will cause APT to upgrade the specified
+<para>
+The following command will cause APT to upgrade the specified
package to the latest version from the <literal/testing/ distribution;
-further upgrades will not occur automatically, however.
+the package will not be upgraded again unless this command is given
+again.
<programlisting>
apt-get install <replaceable>package</replaceable>/testing
</programlisting>
</RefSect2>
- <RefSect2><Title>Tracking Testing</Title>
+ <RefSect2>
+ <Title>Tracking Testing or Unstable</Title>
-<para>The following APT preferences file will cause APT to assign
+<para>
+The following APT preferences file will cause APT to assign
a high priority to package versions from the <literal/testing/
-distribution, a lesser priority to package versions from the
+distribution, a lower priority to package versions from the
<literal/unstable/ distribution, and a prohibitively low priority
to package versions from other <literal/Debian/ distributions.
@@ -512,8 +529,8 @@
</para>
<para>
-With the above APT preferences file, any of the
-following commands will cause APT to upgrade to the latest
+With a suitable &sources-list; file and the above preferences file,
+any of the following commands will cause APT to upgrade to the latest
<literal/testing/ version(s).
<programlisting>
@@ -525,9 +542,11 @@
<para>The following command will cause APT to upgrade the specified
package to the latest version from the <literal/unstable/ distribution.
-Thereafter, <command>apt-get dist-upgrade</command> and the others
-<emphasis/will/ cause upgrade of the package to the latest
-<literal/unstable/ version.
+Thereafter, <command>apt-get upgrade</command> will upgrade
+the package to the most recent <literal/testing/ version if that is
+more recent than the installed version, otherwise, to the most recent
+<literal/unstable/ version if that is more recent than the installed
+version.
<programlisting>
apt-get install <replaceable>package</replaceable>/unstable
@@ -537,10 +556,12 @@
</RefSect2>
</RefSect1>
- <RefSect1><Title>See Also</>
+<RefSect1>
+<Title>See Also</Title>
<para>
&apt-get; &apt-cache; &apt-conf; &sources-list;
- </RefSect1>
+</para>
+</RefSect1>
&manbugs;
&manauthor;
Reply to: