====== Upgrading Configuration Files with a three-way File Merge ==
===== Problem ==

When upgrading software (e.g. with [[slack_upgrade|slackpkg]]) you usually have customized the config files to your personal need. Now the config files of the new software version also differ from the original version. What you want is an easy way to get your own modifications into the new config files.

===== Solution ==

The solution is exemplified with just 1 configuration file called ''conf'':

  * ''conf.org'' is the original config file of old version of the software. Eighter you have created that file by copying //before// you made any modifications to ''conf'' or you can get it again by downloading the old version of the software.
  * ''conf'' is your version of ''conf.org''. You have customized to your needs.
  * ''conf.new'' is the brandnew pristine version coming from the upgrade.

The following command merges both the differences between ''conf.org'' and ''conf'' and the differences between ''conf.org'' and ''conf.new'' back into ''conf'':

  merge conf conf.org conf.new

After merging it is advisable to rename conf.new to be prepared for a future update:

  mv conf.new conf.org

<note tip>All ''*.org'' files can serve as a reminder for you to trace back all the modifications you did to the system. But sometimes you have to create a config file which did not exist before (e.g. ''myConfigFile''). In order not to forget such files during update, it is advisable to create an //empty// counterpart file ''myConfFile.org''.</note>

===== Example where the tools fail ==

A manual check after the patch is applied is advisable, for there are situations imaginable where the tools do not produce the expected results:

<code>
conf.org:      conf:       conf.new:     desired:    result:

[mitwitz]      [mitwitz]   [coburg]      [coburg]    [coburg]
Otto=5         Otto=5      Otto=5        Otto=5      Otto=5
Guenter=6      Guenter=6   Guenter=6     Guenter=6   Guenter=6
Harry=7        Harry=7     Harry=7       Harry=7     Harry=7
Franz=8        Franz=-999  Franz=8       Franz=8     Franz=-999
Helga=9        Helga=9     Helga=9       Helga=9     Helga=9
Egon=10        Egon=10     Egon=10       Egon=10     Egon=10
Anton=11       Anton=11    Anton=11      Anton=11    Anton=11
                           [mitwitz]     [mitwitz]   [mitwitz]
                           Otto=5        Otto=5      Otto=5
                           Guenter=6     Guenter=6   Guenter=6
                           Harry=7       Harry=7     Harry=7
                           Franz=8       Franz=-999  Franz=8
                           Helga=9       Helga=9     Helga=9
</code>

===== Alternatives ==

  * An alternative to the ''merge'' command is ''diff3'', it should produce the same result:<code bash>
diff3 -m conf conf.org conf.new > conf.out
mv conf.out conf
</code>
  * A 2nd alternative to merge are the diff/patch tools. See [[diff patch tips]]