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.
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.
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"?
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.
(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.
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.
(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.
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.
(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.
* 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.
(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!
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
I completely forgot about this -- sorry! Patch posted for review here: https://archives.gentoo.org/gentoo-portage-dev/message/2d623e49d78e23f4e18509c7d5a7f663
This is now in git: https://gitweb.gentoo.org/proj/portage.git/commit/?id=3ff375e832d469f03dc922f7a30651726f86d3e0
Fixed in 2.3.0.
