NAME

       doc_tutorials_elektra-merge-integration_mdHow-To: Integrate elektra-merge Into a Debian Package
        - This guide explains how to use ucf's new --three-way-merge-command functionality in conjunction with
       Elektra in order to ultilize Elektra's powerful tools in order to allow automatic three-way merges of
       your package's configuration during upgrades in a way that is more reliable than a diff3 merge. This
       guide assumes that you are familiar with ucf already and are just trying to implement the --three-way-
       merge-command option using Elektra.

   The New Option
       The addition of the --three-way-merge-command option was a part of my Google Summer of Code Project. This
       option takes the form: --three-way-merge-command command <New file>=''> <Destination>

       Where command is the command you would like to use for the merge. New File and Destination are the same
       as always.

   elektra-merge
       We added a new script to Elektra called elektra-merge for use with this new option in ucf. This script
       acts as a liaison between ucf and Elektra, allowing a regular ucf command to run a kdb merge even though
       ucf commands only pass New File and Destination whereas kdb merge requires ourpath, theirpath, basepath,
       and resultpath. Since ucf already performs a three-way merge, it keeps track of all the necessary files
       to do so, even though it only takes in New File and Destination.

       In order to use elektra-merge, the current configuration file must be mounted to KDB to serve as ours in
       the merge. The script automatically mounts theirs, base, and result using the kdb remount command in
       order to use the same backend as ours (since all versions of the same file should use the same backend
       anyway) and this way users don't need to worry about specifying the backend for each version of the file.
       Then the script attempts a merge on the newly mounted KeySets. Once this is finished, either on success
       or not, the script finishes by unmouting all but our copy of the file to cleanup KDB. Then, if the merge
       was successful ucf will replace ours with the result providing the package with an automatically merged
       configuration which will also be updated in KDB itself.

       Additionally, we added two other scripts, elektra-mount and elektra-umount which act as simple wrappers
       for kdb mount and kdb umount. That work identically but are more script friendly.

   The Full Command
       The full command to use elektra-merge to perform a three-way merge on a file managed by ucf is: ucf
       --three-way --threeway-merge-command elektra-merge <New file>=''> <Destination>

       Thats it! As described above, elektra-merge is smart enough to run the whole merge off of the information
       from that command and utilizes the new kdb remount command to do so.

   How-To Integrate
       Integrating elektra-merge into a package that already uses ucf is very easy! In postinst you should have
       a line similar to: ucf <New file>=''> <Destination>

       or perhaps: ucf --three-way <New file>=''> <Destination>

       All you must do is in postinst, when run with the configure option you must mount the config file to
       Elektra: kdb elektra-mount <New file>=''> <Mouting destination>=''> <Backend>

       Next, you must update the line containing ucf with the options --three-way and --threeway-merge-command
       like so: ucf --three-way --threeway-merge-command elektra-merge <New file>=''> <Destination>

       Then, in your postrm script, during a purge, you must umount the config file before deleting it: kdb
       elektra-umount <name>

       That's it! With those small changes you can use Elektra to perform automatic three-way merges on any
       files that your package uses ucf to handle!

   Example
       Below is a diff representing the changes we made to the samba-common package in order to allow automatic
       configuration merging for smb.conf using Elektra. We chose this package because it already uses ucf to
       handle smb.conf but it frequently requires users to manually merge changes across versions. Here is the
       patch showing what we changed:

           diff samba_orig/samba-3.6.6/debian/samba-common.postinst samba/samba-3.6.6/debian/samba-common.postinst
           92c92,93
           < ucf --three-way --debconf-ok "$NEWFILE" "$CONFIG"
           ---
           > kdb elektra-mount "$CONFIG" system/samba/smb ini
           > ucf --three-way --threeway-merge-command elektra-merge --debconf-ok "$NEWFILE" "$CONFIG"
           Only in samba/samba-3.6.6/debian/: samba-common.postinst~
           diff samba_orig/samba-3.6.6/debian/samba-common.postrm samba/samba-3.6.6/debian/samba-common.postrm
           4a5
           >       kdb elektra-umount system/samba/smb

       As you can see, all we had to do was add the line to mount smb.conf during install, update the ucf
       command to include the new --threeway-merge-command option, and unmount system/samba/smb during a purge.
       It really is that easy!

Version 0.8.14                                   Mon Jul 24 doc7tutorials_elektra-merge-integration_md(3elektra)