[Bug 2003759] [NEW] apt phasing should be documented in apt.conf(5) rather than apt_preferences(5)

[Seth Arnold]

Public bug reported:

Hello, the apt documentation on controlling apt phasing is in
apt_preferences(5). However, putting the records into a file in
/etc/apt/preferences.d leads to an error:

$ rg -l APT::Machine-ID  -g '*.xml'
apt_2.2.2ubuntu1/doc/apt_preferences.5.xml
apt_2.3.10/doc/apt_preferences.5.xml
apt_2.3.7/doc/apt_preferences.5.xml
apt_2.1.17/doc/apt_preferences.5.xml
apt_2.3.3/doc/apt_preferences.5.xml
apt_2.3.9/doc/apt_preferences.5.xml
apt_2.4.8/doc/apt_preferences.5.xml
apt_2.2.3/doc/apt_preferences.5.xml
apt_2.5.0/doc/apt_preferences.5.xml
apt_2.4.5/doc/apt_preferences.5.xml
apt_2.3.13/doc/apt_preferences.5.xml
apt_2.2.1/doc/apt_preferences.5.xml
apt_2.3.11/doc/apt_preferences.5.xml
apt_2.3.6/doc/apt_preferences.5.xml
apt_2.1.16/doc/apt_preferences.5.xml
apt_2.3.9ubuntu0.1/doc/apt_preferences.5.xml
apt_2.5.3/doc/apt_preferences.5.xml
apt_2.4.0/doc/apt_preferences.5.xml
apt_2.3.5/doc/apt_preferences.5.xml
apt_2.2.2/doc/apt_preferences.5.xml
apt_2.3.15build1/doc/apt_preferences.5.xml
apt_2.3.15/doc/apt_preferences.5.xml
apt_2.3.8/doc/apt_preferences.5.xml
apt_2.2.4ubuntu0.1/doc/apt_preferences.5.xml
apt_2.4.3/doc/apt_preferences.5.xml
apt_2.1.18/doc/apt_preferences.5.xml


⏚ [sarnold:/etc/apt] $ sudo vim /etc/apt/preferences.d/phased-updates
[sudo] password for sarnold: 
⏚ [sarnold:/etc/apt] 11s $ apt list
E: Invalid record in the preferences file /etc/apt/preferences.d/phased-updates, no Package header
⏚ [sarnold:/etc/apt] $ cat /etc/apt/preferences.d/phased-updates
// To have all your machines phase the same, set the same string in this field
// If commented out, apt will use /etc/machine-id to seed the random number generator
APT::Machine-ID "aaaabbbbccccddddeeeeffff";

// Always include phased updates
APT::Get::Always-Include-Phased-Updates "1";

// Never include phased updates
# APT::Get::Never-Include-Phased-Updates "1";


Considering how difficult it is to tell which of preferences vs conf should be used for which settings, mentioning phasing in both manpages would be very kind. However, both manpages should be clear about which one is actually correct.

Thanks

** Affects: apt (Ubuntu)
     Importance: Undecided
         Status: New

-- 
You received this bug notification because you are a member of Ubuntu
Foundations Bugs, which is subscribed to apt in Ubuntu.
https://bugs.launchpad.net/bugs/2003759

Title:
  apt phasing should be documented in apt.conf(5) rather than
  apt_preferences(5)

Status in apt package in Ubuntu:
  New

Bug description:
  Hello, the apt documentation on controlling apt phasing is in
  apt_preferences(5). However, putting the records into a file in
  /etc/apt/preferences.d leads to an error:

  $ rg -l APT::Machine-ID  -g '*.xml'
  apt_2.2.2ubuntu1/doc/apt_preferences.5.xml
  apt_2.3.10/doc/apt_preferences.5.xml
  apt_2.3.7/doc/apt_preferences.5.xml
  apt_2.1.17/doc/apt_preferences.5.xml
  apt_2.3.3/doc/apt_preferences.5.xml
  apt_2.3.9/doc/apt_preferences.5.xml
  apt_2.4.8/doc/apt_preferences.5.xml
  apt_2.2.3/doc/apt_preferences.5.xml
  apt_2.5.0/doc/apt_preferences.5.xml
  apt_2.4.5/doc/apt_preferences.5.xml
  apt_2.3.13/doc/apt_preferences.5.xml
  apt_2.2.1/doc/apt_preferences.5.xml
  apt_2.3.11/doc/apt_preferences.5.xml
  apt_2.3.6/doc/apt_preferences.5.xml
  apt_2.1.16/doc/apt_preferences.5.xml
  apt_2.3.9ubuntu0.1/doc/apt_preferences.5.xml
  apt_2.5.3/doc/apt_preferences.5.xml
  apt_2.4.0/doc/apt_preferences.5.xml
  apt_2.3.5/doc/apt_preferences.5.xml
  apt_2.2.2/doc/apt_preferences.5.xml
  apt_2.3.15build1/doc/apt_preferences.5.xml
  apt_2.3.15/doc/apt_preferences.5.xml
  apt_2.3.8/doc/apt_preferences.5.xml
  apt_2.2.4ubuntu0.1/doc/apt_preferences.5.xml
  apt_2.4.3/doc/apt_preferences.5.xml
  apt_2.1.18/doc/apt_preferences.5.xml

  
  ⏚ [sarnold:/etc/apt] $ sudo vim /etc/apt/preferences.d/phased-updates
  [sudo] password for sarnold: 
  ⏚ [sarnold:/etc/apt] 11s $ apt list
  E: Invalid record in the preferences file /etc/apt/preferences.d/phased-updates, no Package header
  ⏚ [sarnold:/etc/apt] $ cat /etc/apt/preferences.d/phased-updates
  // To have all your machines phase the same, set the same string in this field
  // If commented out, apt will use /etc/machine-id to seed the random number generator
  APT::Machine-ID "aaaabbbbccccddddeeeeffff";

  // Always include phased updates
  APT::Get::Always-Include-Phased-Updates "1";

  // Never include phased updates
  # APT::Get::Never-Include-Phased-Updates "1";

  
  Considering how difficult it is to tell which of preferences vs conf should be used for which settings, mentioning phasing in both manpages would be very kind. However, both manpages should be clear about which one is actually correct.

  Thanks

To manage notifications about this bug go to:
https://bugs.launchpad.net/ubuntu/+source/apt/+bug/2003759/+subscriptions