Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!

Bug 543706

Summary: sys-apps/portage - please improve emerge's "config files need updating" output / doc reference
Product: Portage Development Reporter: Ben Kohler <bkohler>
Component: DocumentationAssignee: Portage team <dev-portage>
Status: RESOLVED FIXED    
Severity: normal CC: bkohler
Priority: Normal Keywords: InVCS
Version: unspecified   
Hardware: All   
OS: Linux   
Whiteboard:
Package list:
Runtime testing required: ---
Bug Depends on:    
Bug Blocks: 573774    

Description Ben Kohler gentoo-dev 2015-03-18 17:02:34 UTC
Currently the emerge output for new config files is something like this:

 * IMPORTANT: 3 config files in '/etc' need updating.                           
 * See the CONFIGURATION FILES section of the emerge                            
 * man page to learn how to update config files.

However, this man page section is not at ALL suitable for new users, this is mostly a developer's reference or at least a very advanced user's reference.  The very last small paragraph of that man page section is what users really need to see.  I'd suggest this either be moved to the top of this man section (slightly reworded, as an intro/summary), or that a new section be created for it.  I'd be happy to help with rewording once we have some idea which way we're going with the change.

For reference, here is the current man page section that we're suggesting day-one gentoo users read through just to learn that they need to run dispatch-conf (or his favorite alternative):


CONFIGURATION FILES
       Portage has a special feature called "config file protection". The pur‐
       pose of this feature is to prevent new package installs from clobbering
       existing configuration files. By default,  config  file  protection  is
       turned on for /etc and the KDE configuration dirs; more may be added in
       the future.

       When Portage installs a file into a protected directory tree like /etc,
       any  existing files will not be overwritten. If a file of the same name
       already exists, Portage will change the  name  of  the  to-be-installed
       file  from 'foo' to ´._cfg0000_foo´. If ´._cfg0000_foo´ already exists,
       this name becomes ´._cfg0001_foo´, etc. In this way, existing files are
       not  overwritten,  allowing the administrator to manually merge the new
       config files and avoid any unexpected changes.

       In addition to protecting overwritten files, Portage  will  not  delete
       any  files from a protected directory when a package is unmerged. While
       this may be a little bit untidy, it does prevent  potentially  valuable
       config files from being deleted, which is of paramount importance.

       Protected  directories  are set using the CONFIG_PROTECT variable, nor‐
       mally defined in make.globals. Directory exceptions to the  CONFIG_PRO‐
       TECTed directories can be specified using the CONFIG_PROTECT_MASK vari‐
       able.  To find files that need to be updated in /etc,  type  find  /etc
       -name '._cfg????_*'.

       You   can  disable  this  feature  by  setting  CONFIG_PROTECT="-*"  in
       make.conf(5).  Then, Portage will mercilessly auto-update  your  config
       files.  Alternatively, you can leave Config File Protection on but tell
       Portage that it can overwrite files in certain specific /etc  subdirec‐
       tories. For example, if you wanted Portage to automatically update your
       rc scripts and your wget  configuration,  but  didn't  want  any  other
       changes  made  without  your  explicit  approval,  you'd  add  this  to
       make.conf(5):

       CONFIG_PROTECT_MASK="/etc/wget /etc/rc.d"

       Tools such as dispatch-conf, cfg-update, and etc-update are also avail‐
       able  to  aid  in  the merging of these files. They provide interactive
       merging and can auto-merge trivial changes.
Comment 1 Alexander Berntsen (RETIRED) gentoo-dev 2015-03-19 17:45:22 UTC
Personally I prefer the way it is today, which indirectly forces the user to read up a bit. But I'd be happy to entertain a patch that changes things up a bit.
Comment 2 Ben Kohler gentoo-dev 2015-03-19 19:02:03 UTC
You have to be kidding.  It actually says "To find files that need to be updated in /etc, type find /etc -name '._cfg????_*'", as though that is the preferred method of handling new configs.  Have you EVER heard of someone using that method day to day? Then a minor note at the bottom mentions disaptch-conf/etc-update/etc, that can "also" be used to manage configs.

You really think it's acceptable that a new user who's been on gentoo 30 mins has to read all that, and run a crazy find command, rather than just telling them "run dispatch-conf to see files which need merging"?
Comment 3 Ben Kohler gentoo-dev 2015-03-19 19:05:15 UTC
I should mention, now that autounmask is default-on, and "emerge --ask anymaskedpackage" will automatically fire up autounmask-write, users are hitting this VERY EARLY in their gentoo lives.  

And they're all clueless as to what they need to do with configs, so you end up seeing emerge logs with "38 config files in /etc need updating".  And it's because this is the WRONG doc to be pointing new users at, at least in its current state.
Comment 4 Alexander Berntsen (RETIRED) gentoo-dev 2015-03-20 02:33:53 UTC
(In reply to Ben Kohler from comment #2)
> You have to be kidding. 
No.

> It actually says "To find files that need to be  updated in /etc, type
> find /etc -name '._cfg????_*'", as though that is the preferred method
> of handling new configs.
It doesn't say that it is the preferred method of handling new configurations.

> Have you EVER heard of someone using that method day to day?
Irrelevant.

> Then a minor note at the bottom mentions disaptch-conf/etc-update/etc,
> that can "also" be used to manage configs.
Yes.

> You really think it's acceptable that a new user who's been on gentoo 30
> mins has to read all that, and run a crazy find command, rather than just
> telling them "run dispatch-conf to see files which need merging"?
Yes.

(In reply to Ben Kohler from comment #3)
> I should mention, now that autounmask is default-on, and "emerge --ask
> anymaskedpackage" will automatically fire up autounmask-write, users are
> hitting this VERY EARLY in their gentoo lives. 
I know.

> And they're all clueless as to what they need to do with configs, so you end
> up seeing emerge logs with "38 config files in /etc need updating".
Yes. Maybe they should learn how to Gentoo.

> And it's because this is the WRONG doc to be pointing new users at, at
> least in its current state.
I disagree.


Patches still welcome.
Comment 5 Brian Dolbec (RETIRED) gentoo-dev 2015-03-20 03:11:55 UTC
I disagree with you Alexander.  I like to find the main information quickly, and dig into more details as needed.  It is very frustrating to read over and decipher a big block of test to find the simple solution.

I agree with Ben, as I discussed with Ben in irc, the second paragraph should mention the main apps that handle merging the config changes.  Along with whatever references to other man pages for those apps.  It should then add a sub-header "Detailing" the config protect system.
Comment 6 Alexander Berntsen (RETIRED) gentoo-dev 2015-03-20 03:21:09 UTC
(In reply to Brian Dolbec from comment #5)
> I disagree with you Alexander.  I like to find the main information quickly,
> and dig into more details as needed.  It is very frustrating to read over
> and decipher a big block of test to find the simple solution.
The section is about how configuration files work. "obtw you can use these tools to merge them" is barely relevant in the first place. This is just emerge's man page, so it should focus on detailing how emerge works. If reading is frustrating then computers will be frustrating for some time yet.

> I agree with Ben, as I discussed with Ben in irc, the second paragraph
> should mention the main apps that handle merging the config changes.  Along
> with whatever references to other man pages for those apps.  It should then
> add a sub-header "Detailing" the config protect system.
I disagree. The tl;dr/obtw should be at the bottom.

If the user wants some command they can copypasta into BASH, hoping it doesn't fuck up their system, they should look in a Wiki, not the man page.


Still happy to look at a patch.
Comment 7 Ben Kohler gentoo-dev 2015-03-20 03:35:01 UTC
It sounds like you would rather keep the man page intact, and point new users at another document.  I'm onboard with that.  But if your whole idea is just "fuck new users, it's supposed to be hard", I'm not onboard with that.

I'm more than willing to write patches, I'm soliciting input here before I get started.  Sorry I didn't make that clear in this bug report.
Comment 8 Alexander Berntsen (RETIRED) gentoo-dev 2015-03-20 03:43:02 UTC
(In reply to Ben Kohler from comment #7)
> It sounds like you would rather keep the man page intact, and point new
> users at another document.  I'm onboard with that.
It sounds like you want a "trust me, just run this command", and this belongs in a Wiki rather than a man page.

> But if your whole idea is just "fuck new users, it's supposed to be hard",
> I'm not onboard with that.
I do not intend to have sexual relations with new (or old) users -- even if it were hard.

It is difficult, and will remain so due to the inherent complexity -- regardless of whether it is "supposed" to be or not.

> I'm more than willing to write patches[.]
Great.
Comment 9 Julian Ospald 2015-03-21 23:41:31 UTC
 * IMPORTANT: 3 config files in '/etc' need updating.                           
 * See the CONFIGURATION FILES and CONFIGURATION FILES UPDATE TOOLS
 * sections of the emerge man page to learn how to update config files.

CONFIGURATION FILES
       Portage has a special feature called "config file protection". The pur‐
       pose of this feature is to prevent new package installs from clobbering
       existing configuration files. By default,  config  file  protection  is
       turned on for /etc and the KDE configuration dirs; more may be added in
       the future.

       When Portage installs a file into a protected directory tree like /etc,
       any  existing files will not be overwritten. If a file of the same name
       already exists, Portage will change the  name  of  the  to-be-installed
       file  from 'foo' to ´._cfg0000_foo´. If ´._cfg0000_foo´ already exists,
       this name becomes ´._cfg0001_foo´, etc. In this way, existing files are
       not  overwritten,  allowing the administrator to manually merge the new
       config files and avoid any unexpected changes.

       In addition to protecting overwritten files, Portage  will  not  delete
       any  files from a protected directory when a package is unmerged. While
       this may be a little bit untidy, it does prevent  potentially  valuable
       config files from being deleted, which is of paramount importance.

       Protected  directories  are set using the CONFIG_PROTECT variable, nor‐
       mally defined in make.globals. Directory exceptions to the  CONFIG_PRO‐
       TECTed directories can be specified using the CONFIG_PROTECT_MASK vari‐
       able.  To find files that need to be updated in /etc,  type  find  /etc
       -name '._cfg????_*'.

       You   can  disable  this  feature  by  setting  CONFIG_PROTECT="-*"  in
       make.conf(5).  Then, Portage will mercilessly auto-update  your  config
       files.  Alternatively, you can leave Config File Protection on but tell
       Portage that it can overwrite files in certain specific /etc  subdirec‐
       tories. For example, if you wanted Portage to automatically update your
       rc scripts and your wget  configuration,  but  didn't  want  any  other
       changes  made  without  your  explicit  approval,  you'd  add  this  to
       make.conf(5):

CONFIGURATION FILES UPDATE TOOLS
       Tools such as dispatch-conf, cfg-update, and etc-update are also avail‐
       able  to  aid  in  the merging of these files. They provide interactive
       merging and can auto-merge trivial changes.



This would make it easier for people to skip the block of text if they are just looking for automated update tools.
Comment 10 Alexander Berntsen (RETIRED) gentoo-dev 2015-03-22 14:16:15 UTC
(In reply to Julian Ospald (hasufell) from comment #9)
> This would make it easier for people to skip the block of text if they are
> just looking for automated update tools.

This is fine by me. If the bug reporter thinks it's OK I would be happy to write a patch, unless you want to do that yourself. Thanks!
Comment 11 Ben Kohler gentoo-dev 2015-10-14 18:00:20 UTC
I don't know how I let this bug slip from my mind for so long, but that proposed fix in comment 9 would be great I think
Comment 12 Alexander Berntsen (RETIRED) gentoo-dev 2016-02-01 16:41:09 UTC
I completely forgot about this -- sorry! Patch posted for review here: https://archives.gentoo.org/gentoo-portage-dev/message/2d623e49d78e23f4e18509c7d5a7f663
Comment 13 Alexander Berntsen (RETIRED) gentoo-dev 2016-02-02 10:11:38 UTC
This is now in git: https://gitweb.gentoo.org/proj/portage.git/commit/?id=3ff375e832d469f03dc922f7a30651726f86d3e0
Comment 14 Zac Medico gentoo-dev 2017-08-11 20:11:52 UTC
Fixed in 2.3.0.