\subsection*{Introduction}

The kdb tool allows users to access and perform functions on the Elektra Key Database from the command line. We added a new command to this very useful tool, the merge command. This command allows a user to perform a three-\/way merge of Key\+Sets from the kdb tool.

The command to use this tool is\+: \begin{DoxyVerb}    kdb merge [options] ourpath theirpath basepath resultpath
\end{DoxyVerb}


The standard naming scheme for a three-\/way merge consists of ours, theirs, and base\+:
\begin{DoxyItemize}
\item ours refers to the local copy of a file
\item theirs refers to a remote copy
\item base refers to their common ancestor.
\end{DoxyItemize}

This works very similarly for Key\+Sets, especially ones that consist of mounted conffiles.

For mounted conffiles\+:
\begin{DoxyItemize}
\item ours should be the user's copy
\item theirs would be the maintainers copy,
\item base would be the previous version of the maintainer's copy.
\end{DoxyItemize}

If the user is just trying to accomplish is a three-\/way merge using any two arbitrary keysets that share a base, it doesn't matter which ones are defined as ours or theirs as long as they use the correct base Key\+Set. In kdb merge, ourpath, theirpath, and basepath work just like ours, theirs, and base except each one represents the root of a Key\+Set. Resultpath is pretty self-\/explanatory, it is just where you want the result of the merge to be saved under. It's worth noting, resultpath should be empty before attempting a merge, otherwise there can be unintended consquences.

\subsection*{Options}

As for the options, there are a few basic options\+: \begin{DoxyVerb}-i  --interactive                   which attempts the merge in an interactive way

    -t  --test                                      which tests the proposed merge and informs you about possible conflicts

    -f --force                                      which overwrites any Keys in resultpath
\end{DoxyVerb}


\subsubsection*{Strategies}

Additionally there is an option to specify a merge strategy, which is very important.

The option for strategy is\+: \begin{DoxyVerb}    -s --strategy <name>            which is used to specify a strategy to use in case of a conflict
\end{DoxyVerb}


The current list of strategies are\+: \begin{DoxyVerb}    preserve                        the merge will fail if a conflict is detected

    ours                            the merge will use our version during a conflict

    theirs                          the merge will use their version during a conflict

    base                            the merge will use the base version during a conflict
\end{DoxyVerb}


If no strategy is specified, the merge will default to the preserve strategy as to not risk making the wrong decision. If any of the other strategies are specified, when a conflict is detected, merge will use the Key specified by the strategy (ours, theirs, or base) for the resulting Key.

\subsection*{Basic Example}

Basic Usage\+: \begin{DoxyVerb}    kdb merge system/hosts/ours system/hosts/theirs system/hosts/base system/hosts/result
\end{DoxyVerb}


\subsection*{Examples Using Strategies}

Here are examples of the same Key\+Sets being merged using different strateigies. The Key\+Sets are mounted using the simpleini file, the left side of '=' is the name of the Key, the right side is its string value.

We start with the base Key\+Set, system/base\+: \begin{DoxyVerb}    key1=1  
    key2=2  
    key3=3  
    key4=4  
    key5=5  
\end{DoxyVerb}


Here is our Key\+Set, system/ours\+: \begin{DoxyVerb}    key1=apple  
    key2=2  
    key3=3  
    key5=fish  
\end{DoxyVerb}


Here is their Key\+Set, system/theirs\+: \begin{DoxyVerb}    key1=1  
    key2=pie  
    key4=banana  
    key5=5  
\end{DoxyVerb}


Now we will examine the result Key\+Set with the different strategies.

\subsubsection*{Preserve}

\begin{DoxyVerb}    kdb merge -s preserve system/ours system/theirs system/base system/result
\end{DoxyVerb}


The merge will fail because of a conflict for key4 since key4 was deleted in our Key\+Set and edited in their Key\+Set. Since we used preserve, the merge fails and the result Key\+Set is not saved.

\subsubsection*{Ours}

\begin{DoxyVerb}    kdb merge -s ours system/ours system/theirs system/base system/result
\end{DoxyVerb}


The result Key\+Set, system/result will be\+: \begin{DoxyVerb}    key1=apple  
    key2=pie 
    key5=fish  
\end{DoxyVerb}


Because the conflict of key4 (it was deleted in ours but changed in theirs) is solved by using our copy thus deleting the key.

\subsubsection*{Theirs}

\begin{DoxyVerb}    kdb merge -s theirs system/ours system/theirs system/base system/result
\end{DoxyVerb}


The result Key\+Set, system/result will be\+: \begin{DoxyVerb}    key1=apple
    key2=pie
    key4=banana
    key5=fish
\end{DoxyVerb}


Here, the conflict of key4 is solved by using their copy, thus key4=banana.

\subsubsection*{Base}

\begin{DoxyVerb}    kdb merge -s base system/ours system/theirs system/base system/result
\end{DoxyVerb}


The result Key\+Set, system/result will be\+: \begin{DoxyVerb}    key1=apple
    key2=pie
    key4=4
    key5=5
\end{DoxyVerb}


The same conflict is found in key4, but here we use the base version to solve it so key4=4. 