\label{doc_tutorials_merge_md_md_doc_tutorials_merge}%
\Hypertarget{doc_tutorials_merge_md_md_doc_tutorials_merge}%
 \hypertarget{doc_tutorials_merge_md_autotoc_md4366}{}\doxysection{Introduction}\label{doc_tutorials_merge_md_autotoc_md4366}
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 {\ttfamily merge} command. This command allows a user to perform a three-\/way merge of Key\+Sets from the {\ttfamily kdb} tool.

The command to use this tool is\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb merge [options] ourpath theirpath basepath resultpath}
\DoxyCodeLine{\# RET: 7}

\end{DoxyCode}


The standard naming scheme for a three-\/way merge consists of {\ttfamily ours}, {\ttfamily theirs}, and {\ttfamily base}\+:


\begin{DoxyItemize}
\item {\ttfamily ours} refers to the local copy of a file
\item {\ttfamily theirs} refers to a remote copy
\item {\ttfamily base} refers to their common ancestor.
\end{DoxyItemize}

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

For mounted configuration files\+:


\begin{DoxyItemize}
\item {\ttfamily ours} should be the user\textquotesingle{}s copy
\item {\ttfamily theirs} would be the maintainers copy,
\item {\ttfamily base} would be the previous version of the maintainer\textquotesingle{}s copy.
\end{DoxyItemize}

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


\begin{DoxyItemize}
\item {\ttfamily -\/i}, {\ttfamily -\/-\/interactive}\+: which attempts the merge in an interactive way
\item {\ttfamily -\/f}, {\ttfamily -\/-\/force}\+: which overwrites any Keys in {\ttfamily resultpath}
\end{DoxyItemize}\hypertarget{doc_tutorials_merge_md_autotoc_md4368}{}\doxysubsection{Strategies}\label{doc_tutorials_merge_md_autotoc_md4368}
Additionally, there is an option to specify a merge strategy, which is very important.

The option for strategy is\+:


\begin{DoxyItemize}
\item {\ttfamily -\/s $<$name$>$}, {\ttfamily -\/-\/strategy $<$name$>$}\+: which is used to specify a strategy to use in case of a conflict
\end{DoxyItemize}

The current list of strategies are\+:


\begin{DoxyItemize}
\item {\ttfamily preserve}\+: the merge will fail if a conflict is detected
\item {\ttfamily ours}\+: the merge will use our version during a conflict
\item {\ttfamily theirs}\+: the merge will use their version during a conflict
\item {\ttfamily cut}\+: Removes existing keys below the resultpath and replaces them with the merged keyset.
\item {\ttfamily import}\+: (DEPRECATED, avoid using it!) Preserves existing keys in the resultpath if they do not exist in the merged keyset. If the key does exist in the merged keyset, it will be overwritten.
\end{DoxyItemize}

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 ({\ttfamily ours}, {\ttfamily theirs}, {\ttfamily cut} or {\ttfamily import}) for the resulting Key.\hypertarget{doc_tutorials_merge_md_autotoc_md4369}{}\doxysection{Basic Example}\label{doc_tutorials_merge_md_autotoc_md4369}
Basic Usage\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb merge system:/hosts/ours system:/hosts/theirs system:/hosts/base system:/hosts/result}

\end{DoxyCode}
\hypertarget{doc_tutorials_merge_md_autotoc_md4370}{}\doxysection{Examples Using Strategies}\label{doc_tutorials_merge_md_autotoc_md4370}
Here are examples of the same Key\+Sets being merged using different strategies. The Key\+Sets are mounted using a property format, the left side of \textquotesingle{}=\textquotesingle{} is the name of the Key, the right side is its string value.

We start with the base Key\+Set, {\ttfamily system\+:/base}\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{key1=1}
\DoxyCodeLine{key2=2}
\DoxyCodeLine{key3=3}
\DoxyCodeLine{key4=4}
\DoxyCodeLine{key5=5}

\end{DoxyCode}


Here is our Key\+Set, {\ttfamily system\+:/ours}\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{key1=apple}
\DoxyCodeLine{key2=2}
\DoxyCodeLine{key3=3}
\DoxyCodeLine{key5=fish}

\end{DoxyCode}


Here is their Key\+Set, {\ttfamily system\+:/theirs}\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{key1=1}
\DoxyCodeLine{key2=pie}
\DoxyCodeLine{key4=banana}
\DoxyCodeLine{key5=5}

\end{DoxyCode}


To add the keys to the key database, execute the following commands\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb set user:/tests/base/key1 1}
\DoxyCodeLine{\#> Create a new key user:/tests/base/key1 with string "{}1"{}}
\DoxyCodeLine{}
\DoxyCodeLine{kdb set user:/tests/base/key2 2}
\DoxyCodeLine{\#> Create a new key user:/tests/base/key2 with string "{}2"{}}
\DoxyCodeLine{}
\DoxyCodeLine{kdb set user:/tests/base/key3 3}
\DoxyCodeLine{\#> Create a new key user:/tests/base/key3 with string "{}3"{}}
\DoxyCodeLine{}
\DoxyCodeLine{kdb set user:/tests/base/key4 4}
\DoxyCodeLine{\#> Create a new key user:/tests/base/key4 with string "{}4"{}}
\DoxyCodeLine{}
\DoxyCodeLine{kdb set user:/tests/base/key5 5}
\DoxyCodeLine{\#> Create a new key user:/tests/base/key5 with string "{}5"{}}
\DoxyCodeLine{}
\DoxyCodeLine{}
\DoxyCodeLine{kdb set user:/tests/ours/key1 apple}
\DoxyCodeLine{\#> Create a new key user:/tests/ours/key1 with string "{}apple"{}}
\DoxyCodeLine{}
\DoxyCodeLine{kdb set user:/tests/ours/key2 2}
\DoxyCodeLine{\#> Create a new key user:/tests/ours/key2 with string "{}2"{}}
\DoxyCodeLine{}
\DoxyCodeLine{kdb set user:/tests/ours/key3 3}
\DoxyCodeLine{\#> Create a new key user:/tests/ours/key3 with string "{}3"{}}
\DoxyCodeLine{}
\DoxyCodeLine{kdb set user:/tests/ours/key5 fish}
\DoxyCodeLine{\#> Create a new key user:/tests/ours/key5 with string "{}fish"{}}
\DoxyCodeLine{}
\DoxyCodeLine{}
\DoxyCodeLine{kdb set user:/tests/theirs/key1 1}
\DoxyCodeLine{\#> Create a new key user:/tests/theirs/key1 with string "{}1"{}}
\DoxyCodeLine{}
\DoxyCodeLine{kdb set user:/tests/theirs/key2 pie}
\DoxyCodeLine{\#> Create a new key user:/tests/theirs/key2 with string "{}pie"{}}
\DoxyCodeLine{}
\DoxyCodeLine{kdb set user:/tests/theirs/key4 banana}
\DoxyCodeLine{\#> Create a new key user:/tests/theirs/key4 with string "{}banana"{}}
\DoxyCodeLine{}
\DoxyCodeLine{kdb set user:/tests/theirs/key5 5}
\DoxyCodeLine{\#> Create a new key user:/tests/theirs/key5 with string "{}5"{}}

\end{DoxyCode}


Now we will examine the result Key\+Set with the different strategies.\hypertarget{doc_tutorials_merge_md_autotoc_md4371}{}\doxysubsection{Preserve}\label{doc_tutorials_merge_md_autotoc_md4371}

\begin{DoxyCode}{0}
\DoxyCodeLine{kdb merge -\/s preserve user:/tests/ours user:/tests/theirs user:/tests/base user:/tests/result}
\DoxyCodeLine{\# RET: 255}
\DoxyCodeLine{\# STDERR: 1 conflicts were detected that could not be resolved automatically:⏎user:/tests/result/key4⏎ours: CONFLICT\_DELETE, theirs: CONFLICT\_MODIFY⏎⏎Merge unsuccessful.}

\end{DoxyCode}


The merge will fail because of a conflict for {\ttfamily key4} since {\ttfamily 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.\hypertarget{doc_tutorials_merge_md_autotoc_md4372}{}\doxysubsection{Ours}\label{doc_tutorials_merge_md_autotoc_md4372}

\begin{DoxyCode}{0}
\DoxyCodeLine{kdb merge -\/s ours user:/tests/ours user:/tests/theirs user:/tests/base user:/tests/result}

\end{DoxyCode}


The result Key\+Set, {\ttfamily user\+:/tests/result} will be\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb ls user:/tests/result}
\DoxyCodeLine{\#> user:/tests/result/key1}
\DoxyCodeLine{\#> user:/tests/result/key2}
\DoxyCodeLine{\#> user:/tests/result/key5}

\end{DoxyCode}


The values of the keys are\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb get user:/tests/result/key1}
\DoxyCodeLine{\#> apple}
\DoxyCodeLine{}
\DoxyCodeLine{kdb get user:/tests/result/key2}
\DoxyCodeLine{\#> pie}
\DoxyCodeLine{}
\DoxyCodeLine{kdb get user:/tests/result/key5}
\DoxyCodeLine{\#> fish}

\end{DoxyCode}


The conflict of {\ttfamily key4} (it was deleted in {\ttfamily ours} but changed in {\ttfamily theirs}) is solved by using our copy, thus deleting the key.

Now we delete the result keys and try the next merging strategy.


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb rm user:/tests/result/key1}
\DoxyCodeLine{kdb rm user:/tests/result/key2}
\DoxyCodeLine{kdb rm user:/tests/result/key5}

\end{DoxyCode}
\hypertarget{doc_tutorials_merge_md_autotoc_md4373}{}\doxysubsection{Theirs}\label{doc_tutorials_merge_md_autotoc_md4373}

\begin{DoxyCode}{0}
\DoxyCodeLine{kdb merge -\/s theirs user:/tests/ours user:/tests/theirs user:/tests/base user:/tests/result}

\end{DoxyCode}


The result Key\+Set, {\ttfamily user\+:/tests/result} will be\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb ls user:/tests/result}
\DoxyCodeLine{\#> user:/tests/result/key1}
\DoxyCodeLine{\#> user:/tests/result/key2}
\DoxyCodeLine{\#> user:/tests/result/key4}
\DoxyCodeLine{\#> user:/tests/result/key5}

\end{DoxyCode}


The values of the keys are\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb get user:/tests/result/key1}
\DoxyCodeLine{\#> apple}
\DoxyCodeLine{}
\DoxyCodeLine{kdb get user:/tests/result/key2}
\DoxyCodeLine{\#> pie}
\DoxyCodeLine{}
\DoxyCodeLine{kdb get user:/tests/result/key4}
\DoxyCodeLine{\#> banana}
\DoxyCodeLine{}
\DoxyCodeLine{kdb get user:/tests/result/key5}
\DoxyCodeLine{\#> fish}

\end{DoxyCode}


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

We delete the result keys again and finally try the {\ttfamily cut} merging strategy.


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb rm user:/tests/result/key1}
\DoxyCodeLine{kdb rm user:/tests/result/key2}
\DoxyCodeLine{kdb rm user:/tests/result/key4}
\DoxyCodeLine{kdb rm user:/tests/result/key5}

\end{DoxyCode}
\hypertarget{doc_tutorials_merge_md_autotoc_md4374}{}\doxysubsection{Cut}\label{doc_tutorials_merge_md_autotoc_md4374}

\begin{DoxyCode}{0}
\DoxyCodeLine{kdb merge -\/s cut user:/tests/ours user:/tests/theirs user:/tests/base user:/tests/result}

\end{DoxyCode}


The result Key\+Set, {\ttfamily user\+:/tests/result} will be\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb ls user:/tests/result}
\DoxyCodeLine{\#> user:/tests/result/key1}
\DoxyCodeLine{\#> user:/tests/result/key2}
\DoxyCodeLine{\#> user:/tests/result/key4}
\DoxyCodeLine{\#> user:/tests/result/key5}

\end{DoxyCode}


The values of the keys are\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb get user:/tests/result/key1}
\DoxyCodeLine{\#> 1}
\DoxyCodeLine{}
\DoxyCodeLine{kdb get user:/tests/result/key2}
\DoxyCodeLine{\#> pie}
\DoxyCodeLine{}
\DoxyCodeLine{kdb get user:/tests/result/key4}
\DoxyCodeLine{\#> banana}
\DoxyCodeLine{}
\DoxyCodeLine{kdb get user:/tests/result/key5}
\DoxyCodeLine{\#> 5}

\end{DoxyCode}


Here the state of theirs is simply copied to the {\ttfamily resultpath}.\hypertarget{doc_tutorials_merge_md_autotoc_md4375}{}\doxysection{SEE ALSO}\label{doc_tutorials_merge_md_autotoc_md4375}

\begin{DoxyItemize}
\item \mbox{\hyperlink{doc_help_kdb-merge_md}{kdb-\/merge(1)}}
\item \mbox{\hyperlink{doc_help_elektra-merge-strategy_md}{elektra-\/merge-\/strategy(7)}} 
\end{DoxyItemize}