X-Git-Url: https://git.saurik.com/apt.git/blobdiff_plain/a23dcda4a75ead3ef9712d90300f45155856b6ce..37049546fc18d93f4387917bc9b8181e8adeb3fa:/doc/apt_preferences.5.xml?ds=sidebyside
diff --git a/doc/apt_preferences.5.xml b/doc/apt_preferences.5.xml
index 12b03196a..e773ad144 100644
--- a/doc/apt_preferences.5.xml
+++ b/doc/apt_preferences.5.xml
@@ -14,12 +14,13 @@
&apt-email;
&apt-product;
- 29 February 2004
+ 16 February 2010
apt_preferences
5
+ APT
@@ -31,7 +32,8 @@
Description
The APT preferences file /etc/apt/preferences
-can be used to control which versions of packages will be selected
+and the fragment files in the /etc/apt/preferences.d/
+folder can be used to control which versions of packages will be selected
for installation.
Several versions of a package may be available for installation when
@@ -51,6 +53,24 @@ earliest in the &sources-list; file.
The APT preferences file does not affect the choice of instance, only
the choice of version.
+Preferences are a strong power in the hands of a system administrator
+but they can become also their biggest nightmare if used without care!
+APT will not questioning the preferences so wrong settings will therefore
+lead to uninstallable packages or wrong decisions while upgrading packages.
+Even more problems will arise if multiply distribution releases are mixed
+without a good understanding of the following paragraphs.
+Packages included in a specific release aren't tested in and
+therefore doesn't always work as expected in older or newer releases or
+together with other packages from different releases.
+You have been warned.
+
+Note that the files in the /etc/apt/preferences.d
+directory are parsed in alphanumeric ascending order and need to obey the
+following naming convention: The files have no or "pref"
+as filename extension and which only contain alphanumeric, hyphen (-),
+underscore (_) and period (.) characters - otherwise they will be silently
+ignored.
+
APT's Default Priority Assignments
If there is no preferences file or if there is no entry in the file
@@ -60,6 +80,9 @@ 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 apt-get command
line or in the APT configuration file /etc/apt/apt.conf.
+Note that this has precedence over any general priority you set in the
+/etc/apt/preferences file described later, but not
+over specifically pinned packages.
For example,
@@ -143,10 +166,11 @@ 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 specific form assigns a priority (a "Pin-Priority") to one or more
+specified packages and specified version or version range. For example,
the following record assigns a high priority to all versions of
-the perl package whose version number begins with "5.8".
+the perl package whose version number begins with "5.8".
+Multiple packages can be separated by spaces.
Package: perl
@@ -183,7 +207,16 @@ belonging to any distribution whose Archive name is "unstable
Package: *
Pin: release a=unstable
-Pin-Priority: 500
+Pin-Priority: 50
+
+
+The following record assigns a high priority to all package versions
+belonging to any distribution whose Codename is "squeeze".
+
+
+Package: *
+Pin: release n=squeeze
+Pin-Priority: 900
The following record assigns a high priority to all package versions
@@ -323,10 +356,11 @@ file are relevant for setting APT priorities:
-the Archive: line
+the Archive: or Suite: line
names the archive to which all the packages
in the directory tree belong. For example, the line
-"Archive: stable"
+"Archive: stable" or
+"Suite: stable"
specifies that all of the packages in the directory
tree below the parent of the Release file are in a
stable archive. Specifying this value in the APT preferences file
@@ -338,6 +372,22 @@ Pin: release a=stable
+
+the Codename: line
+names the codename to which all the packages
+in the directory tree belong. For example, the line
+"Codename: squeeze"
+specifies that all of the packages in the directory
+tree below the parent of the Release file belong to a version named
+squeeze. Specifying this value in the APT preferences file
+would require the line:
+
+
+Pin: release n=squeeze
+
+
+
+
the Version: line
names the release version. For example, the
@@ -421,7 +471,7 @@ 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
+optional. If omitted, APT assigns a priority of 1 less than the last value
specified on a line beginning with Pin-Priority: release ....
@@ -518,10 +568,74 @@ version.
apt-get install package/unstable
+
+
+
+
+Tracking the evolution of a codename release
+
+The following APT preferences file will cause APT to assign a
+priority higher than the default (500) to all package versions belonging
+to a specified codename of a distribution and a prohibitively low priority to
+package versions belonging to other Debian distributions,
+codenames and archives.
+Note that with this APT preference APT will follow the migration of a release
+from the archive testing to stable and
+later oldstable. If you want to follow for example the progress
+in testing notwithstanding the codename changes you should use
+the example configurations above.
+
+
+Explanation: Uninstall or do not install any Debian-originated package versions
+Explanation: other than those in the distribution codenamed with squeeze or sid
+Package: *
+Pin: release n=squeeze
+Pin-Priority: 900
+
+Explanation: Debian unstable is always codenamed with sid
+Package: *
+Pin: release a=sid
+Pin-Priority: 800
+
+Package: *
+Pin: release o=Debian
+Pin-Priority: -10
+
+
+
+With a suitable &sources-list; file and the above preferences file,
+any of the following commands will cause APT to upgrade to the
+latest version(s) in the release codenamed with squeeze.
+
+apt-get install package-name
+apt-get upgrade
+apt-get dist-upgrade
+
+
+
+The following command will cause APT to upgrade the specified
+package to the latest version from the sid distribution.
+Thereafter, apt-get upgrade will upgrade
+the package to the most recent squeeze version if that is
+more recent than the installed version, otherwise, to the most recent
+sid version if that is more recent than the installed
+version.
+
+
+apt-get install package/sid
+
+
+
+Files
+
+ &file-preferences;
+
+
+
See Also
&apt-get; &apt-cache; &apt-conf; &sources-list;
@@ -531,4 +645,3 @@ apt-get install package/unstable
&manbugs;
-