In most cases files prefixed with
._cfg*  will be created because the user did change a config file. Means the existing config file is different from the one shipped by Gentoo. In practice it is really hard - hard in the sense of big effort and redundant work - to handle such a kind of update. Changes made by a user are usually persistent - thus the user have to do the same steps after each update to prevent that the changes will be overwritten. The not satisfying situation even growth, as such prefixed files are will or could be created, for though the user didn't touch the corresponding config file at all.
Before going on I want to do some naming conventions:
._cfg which is designated to replace the corresponding config file (example:
There are some tools available to handle config file updates, but non of them does the job really good. Some of them did integrate
sdiff  for 3-way-diffs, but I question if this is an effective way for most cases. Sure some manual investigation can't be excluded always. It would go much to far here to do an analysis of what was going wrong there and to philosophize about the reasons behind. At least I think the basic approach was wrong, so let me present a different solution.
The goals we want to reach are:
The challenge is how to handle config files which are present on the system against them provided by Gentoo in their latest version after an update. Update means that the user did run basically an
$ emerge -u <whatever>
<whatever>  stands for additional options and/or parameters, include the name of ebuilds/packages.
Really simple - or it is confusing? For the second I will present an
The example is generic.
qrtconf  has some options to change the process!
Our example config file calls
/etc/vsftpd.conf  and (after an update) the corresponding cfg file is
/etc/._cfg0000_vsftpd.conf  exists. I divided the processing into 3 stages. A higher stage will be reached only, if the actual stage wasn't successful - or in other words: couldn't finish.
A backup of the last version of each config file provided from the distribution will be created automatically at time the corresponding prefixed file was created and handled by qrtconf.
We invoke qrtconf and it searches for prefixed files. It did find
/etc/._cfg0000_vsftpd.conf . Now it looks in
/var/lib/qrtools/  if there does exist a corresponding file
The backup'd files will be stored in
/var/lib/qrtools/  (default) - from this starting point the folder/file hierarchy is the same like in
qrtconf proceeds to
There is no corresponding file. qrtconf moves
/var/lib/qrtools/etc/vnstatd.conf . The processing is finished. Otherwise - in case there is a corresponding file - we go on to
A corresponding file
/var/lib/qrtools/etc/vnstatd.conf  exists. qrtconf uses
diff  to determine differences between
/var/lib/qrtools/etc/vnstatd.conf . If there is no difference, then the prefixed file has the same content as the last config file provided by Gentoo. Thus we come to the following
Conclusion: There are no changes from site of Gentoo, changes MUST be done by the user. It is save to delete the prefixed file
qrtconf deletes the prefixed file and doesn't touch the config file
/etc/vnstatd.conf . Thus the processing is finished, otherwise we have to proceed with
The last possible reason that the prefixed file was created is now, that Gentoo did made changes in their provided config file. qrtconf creates a (temporarily) patch between
/var/lib/qrtools/etc/vnstatd.conf  (input file 1) and
/etc/._cfg0000_vnstatd.conf  (input file 2). Afterwards qrtconf applies the patch to
/etc/vnstatd.conf . Last step is to move the prefixed file to
/var/lib/qrtools/etc/vnstatd.conf  by replacing the former (old) backup'd file.
That's all, processing finished.
From the above we have seen that there are two types of changes which we will name and handle:
Now we can abstract to have and run into one of 4 plus 2 situations (or a maybe in a combination of some):
Situation 1: This is the easiest situation and like basic functionality of
etc-update  the existing config file will be replaced.
Situation 2: This is close to point 1. As there is nothing to replace, a new config file will be created.
Situation 3a): This is the typical use case qrtconf expects and it is the status qrtconf creates after it did run successful.
Situation 3b): Depending on how many changes and how big are the differences are, qrtconf could fail here. Anyhow, qrtconf leaves the config file and the prefixed file untouched then. Usually there is a manual investigation required once.
Situation 4: This isn't a typical use case but it could happen under some circumstances. qrtconf could solve this automatically. Depending on the complexity qrtconf will need 2 update cycles. The config file will may be untouched after the first cycle, but this shouldn't be a issue in most cases - it is just like the prefixed file will be deleted without any other action.
Situation 5: This is an error! It have to be solved manually.
It is much harder to describe (and even understand) all of this than writing the code of qrtconf! But the thoughts behind HAVE TO be clear to prevent circular changes and misunderstandings.
qrtconf has some options (see qrtconf.8). The build-in default values could be overwritten in the config file
/etc/portage/qrtools.conf/qrtconf.conf  (see qrtconf.5). Command line options overwrites config file values. Invalid values causes default values or an error.
By default qrtconf is in interactive mode. This can be deactivated by setting
INTERACTIVE=0  in the config file (recommended). The command line switch
-i  enables the interactive mode only. In interactive mode the verbosity level 0 will be increased to level 1 automatically.
qrtconf has 3 verbosity levels 0 (silent), 1 (verbose) and 2 (more verbose). Default is 1. This setting could be changed via config file or command line switch
-v <N> , where <N> is a level number.