\label{doc_tutorials_cmerge_md_md_doc_tutorials_cmerge}%
\Hypertarget{doc_tutorials_cmerge_md_md_doc_tutorials_cmerge}%
 \hypertarget{doc_tutorials_cmerge_md_autotoc_md3511}{}\doxysection{Introduction}\label{doc_tutorials_cmerge_md_autotoc_md3511}
Elektra takes the semantic aspects of configuration files into account when merging them into one result file. Those configuration files are represented as key sets in Elektra. Key sets are collections of name-\/value pairs.

The {\ttfamily 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 cmerge} command. This command allows a user to perform a three-\/way merge of key sets from the {\ttfamily kdb} tool.

The syntax to use this tool is\+:

{\ttfamily kdb cmerge \mbox{[}OPTIONS\mbox{]} our their base result}

{\ttfamily our}, {\ttfamily their} and {\ttfamily base} represent the three keys that are used in a three-\/way merge. As in the {\ttfamily diff3} tool, required are the three files MYFILE (our), OLDFILE (base) and YOURFILE (their) The result off the three-\/way merge will be stored in {\ttfamily result}.\hypertarget{doc_tutorials_cmerge_md_autotoc_md3512}{}\doxysection{Simple example}\label{doc_tutorials_cmerge_md_autotoc_md3512}
The easiest case is if all three versions contain equal data.


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb set user:/tests/base a}
\DoxyCodeLine{\#> Create a new key user:/tests/base with string "{}a"{}}
\DoxyCodeLine{kdb set user:/tests/their a}
\DoxyCodeLine{\#> Create a new key user:/tests/their with string "{}a"{}}
\DoxyCodeLine{kdb set user:/tests/our a}
\DoxyCodeLine{\#> Create a new key user:/tests/our with string "{}a"{}}
\DoxyCodeLine{kdb cmerge user:/tests/our user:/tests/their user:/tests/base user:/tests/result}
\DoxyCodeLine{kdb get user:/tests/result}
\DoxyCodeLine{\#> a}

\end{DoxyCode}


We change the our key for another example.


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb set user:/tests/our b}
\DoxyCodeLine{\#> Set string to "{}b"{}}

\end{DoxyCode}


Using a {\ttfamily result} path that is not empty gives an error. The option {\ttfamily -\/f} can be used to override. {\bfseries{Attention!}} This deletes existing keys below {\ttfamily result}.


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb cmerge user:/tests/our user:/tests/their user:/tests/base user:/tests/result}
\DoxyCodeLine{\# RET: 3}
\DoxyCodeLine{\# There are keys in the result path. Use -\/f to override them.}
\DoxyCodeLine{kdb cmerge -\/f user:/tests/our user:/tests/their user:/tests/base user:/tests/result}
\DoxyCodeLine{kdb get user:/tests/result}
\DoxyCodeLine{\#> b}

\end{DoxyCode}


We can use the same key multiple times in a single call to cmerge.


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb set user:/tests/same a}
\DoxyCodeLine{\#> Create a new key user:/tests/same with string "{}a"{}}
\DoxyCodeLine{kdb cmerge -\/f user:/tests/same user:/tests/same user:/tests/same user:/tests/result}
\DoxyCodeLine{kdb get user:/tests/result}
\DoxyCodeLine{\#> a}

\end{DoxyCode}
\hypertarget{doc_tutorials_cmerge_md_autotoc_md3513}{}\doxysubsection{hosts}\label{doc_tutorials_cmerge_md_autotoc_md3513}
As a real-\/world example, we import three different (see the comment) versions of a hosts file.


\begin{DoxyCode}{0}
\DoxyCodeLine{echo "{}127.0.0.1       localhost}
\DoxyCodeLine{127.0.1.1       computer}
\DoxyCodeLine{}
\DoxyCodeLine{\# BASE The following lines are desirable for IPv6 capable hosts}
\DoxyCodeLine{::1     ip6-\/localhost ip6-\/loopback}
\DoxyCodeLine{fe00::0 ip6-\/localnet}
\DoxyCodeLine{ff00::0 ip6-\/mcastprefix}
\DoxyCodeLine{ff02::1 ip6-\/allnodes}
\DoxyCodeLine{ff02::2 ip6-\/allrouters"{} | kdb import user:/tests/hosts/base hosts}
\DoxyCodeLine{}
\DoxyCodeLine{echo "{}127.0.0.1       localhost}
\DoxyCodeLine{127.0.1.1       computer}
\DoxyCodeLine{}
\DoxyCodeLine{\# OUR The following lines are desirable for IPv6 capable hosts}
\DoxyCodeLine{::1     ip6-\/localhost ip6-\/loopback}
\DoxyCodeLine{fe00::0 ip6-\/localnet}
\DoxyCodeLine{ff00::0 ip6-\/mcastprefix}
\DoxyCodeLine{ff02::1 ip6-\/allnodes}
\DoxyCodeLine{ff02::2 ip6-\/allrouters"{} | kdb import user:/tests/hosts/our hosts}
\DoxyCodeLine{}
\DoxyCodeLine{echo "{}127.0.0.1       localhost}
\DoxyCodeLine{127.0.1.1       computer}
\DoxyCodeLine{}
\DoxyCodeLine{\# THEIR The following lines are desirable for IPv6 capable hosts}
\DoxyCodeLine{::2     ip6-\/localhost ip6-\/loopback}
\DoxyCodeLine{fe00::0 ip6-\/localnet}
\DoxyCodeLine{ff00::0 ip6-\/mcastprefix}
\DoxyCodeLine{ff02::1 ip6-\/allnodes}
\DoxyCodeLine{ff02::2 ip6-\/allrouters"{} | kdb import user:/tests/hosts/their hosts}
\DoxyCodeLine{}
\DoxyCodeLine{kdb cmerge user:/tests/hosts/our user:/tests/hosts/their user:/tests/hosts/base user:/tests/hosts/result}

\end{DoxyCode}


The merge notices that only one of the three versions of the key {\ttfamily ip6-\/localhost} has changed. Assuming that this was an update it puts the new value in the result.


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb get user:/tests/hosts/result/ipv6/ip6-\/localhost}
\DoxyCodeLine{\#> ::2}

\end{DoxyCode}
\hypertarget{doc_tutorials_cmerge_md_autotoc_md3514}{}\doxysection{Metadata}\label{doc_tutorials_cmerge_md_autotoc_md3514}
Metadata gets merged as well. We do not follow a complicated approach for this topic. When a key-\/value pair is chosen from the three versions to be present in the result it takes all its metadata with it.

In case that the values of some keys are equal, the {\ttfamily our} version wins and consequently the metadata of the {\ttfamily our} version is used. The reason for this is that users might have used the metadata for personal comments.

To demonstrate this, we continue the hosts example\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb meta-\/get user:/tests/hosts/result/ipv6/ip6-\/localhost comment/\#2}
\DoxyCodeLine{\#>  THEIR The following lines are desirable for IPv6 capable hosts}

\end{DoxyCode}


We set up some keys\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb set user:/tests/meta/base equal}
\DoxyCodeLine{\#> Create a new key user:/tests/meta/base with string "{}equal"{}}
\DoxyCodeLine{kdb meta-\/set user:/tests/meta/base comment/\#0 "{}This is the original inline comment"{}}
\DoxyCodeLine{kdb meta-\/set user:/tests/meta/base comment/\#1 "{}This is the first line of the original comment above the key"{}}
\DoxyCodeLine{kdb meta-\/set user:/tests/meta/base comment/\#2 "{}This is the second line of the original comment above the key"{}}
\DoxyCodeLine{}
\DoxyCodeLine{kdb set user:/tests/meta/their equal}
\DoxyCodeLine{\#> Create a new key user:/tests/meta/their with string "{}equal"{}}
\DoxyCodeLine{kdb meta-\/set user:/tests/meta/their comment/\#0 "{}This is their inline comment"{}}
\DoxyCodeLine{kdb meta-\/set user:/tests/meta/their comment/\#1 "{}This is the first line of their comment above the key"{}}
\DoxyCodeLine{kdb meta-\/set user:/tests/meta/their comment/\#2 "{}This is the second line of their comment above the key"{}}
\DoxyCodeLine{}
\DoxyCodeLine{kdb set user:/tests/meta/our equal}
\DoxyCodeLine{\#> Create a new key user:/tests/meta/our with string "{}equal"{}}
\DoxyCodeLine{kdb meta-\/set user:/tests/meta/our comment/\#0 "{}This is your custom inline comment"{}}
\DoxyCodeLine{kdb meta-\/set user:/tests/meta/our comment/\#1 "{}This is the first line of your custom comment above the key"{}}
\DoxyCodeLine{kdb meta-\/set user:/tests/meta/our comment/\#2 "{}This is the second line of your custom comment above the key"{}}
\DoxyCodeLine{}
\DoxyCodeLine{kdb cmerge user:/tests/meta/our user:/tests/meta/their user:/tests/meta/base user:/tests/meta/metaFromOur}

\end{DoxyCode}


Now we can check if the metadata has been merged as expected.


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb meta-\/get user:/tests/meta/metaFromOur comment/\#0}
\DoxyCodeLine{\#> This is your custom inline comment}
\DoxyCodeLine{kdb meta-\/get user:/tests/meta/metaFromOur comment/\#1}
\DoxyCodeLine{\#> This is the first line of your custom comment above the key}
\DoxyCodeLine{kdb meta-\/get user:/tests/meta/metaFromOur comment/\#2}
\DoxyCodeLine{\#> This is the second line of your custom comment above the key}

\end{DoxyCode}


If a key is part of the result because its value has changed then the result will also contain the metadata of that key.


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb set user:/tests/meta/their different}
\DoxyCodeLine{\#> Set string to "{}different"{}}
\DoxyCodeLine{}
\DoxyCodeLine{kdb cmerge user:/tests/meta/our user:/tests/meta/their user:/tests/meta/base user:/tests/meta/metaFromChanged}

\end{DoxyCode}


We can test again if the result meets our expectations.


\begin{DoxyCode}{0}
\DoxyCodeLine{kdb meta-\/get user:/tests/meta/metaFromChanged comment/\#2}
\DoxyCodeLine{\#> This is the second line of their comment above the key}

\end{DoxyCode}
\hypertarget{doc_tutorials_cmerge_md_autotoc_md3515}{}\doxysection{Arrays}\label{doc_tutorials_cmerge_md_autotoc_md3515}
cmerge uses Lib\+Git2 to handle arrays in an efficient manner.


\begin{DoxyCode}{0}
\DoxyCodeLine{echo "{}one\(\backslash\)}
\DoxyCodeLine{two\(\backslash\)}
\DoxyCodeLine{three\(\backslash\)}
\DoxyCodeLine{four\(\backslash\)}
\DoxyCodeLine{five"{} | kdb import user:/tests/arrays/original line}
\DoxyCodeLine{}
\DoxyCodeLine{echo "{}previous\(\backslash\)}
\DoxyCodeLine{one\(\backslash\)}
\DoxyCodeLine{two\(\backslash\)}
\DoxyCodeLine{three\(\backslash\)}
\DoxyCodeLine{four\(\backslash\)}
\DoxyCodeLine{five"{} | kdb import user:/tests/arrays/changed line}
\DoxyCodeLine{}
\DoxyCodeLine{kdb cmerge -\/f user:/tests/arrays/changed user:/tests/arrays/original user:/tests/arrays/original user:/tests/arrays/result}
\DoxyCodeLine{}
\DoxyCodeLine{kdb get user:/tests/arrays/result/\#0}
\DoxyCodeLine{\#> previous}

\end{DoxyCode}
\hypertarget{doc_tutorials_cmerge_md_autotoc_md3516}{}\doxysection{Scripts}\label{doc_tutorials_cmerge_md_autotoc_md3516}
There are two tools of which cmerge is the central tool\+:


\begin{DoxyEnumerate}
\item \mbox{\hyperlink{doc_help_kdb-install-config-file_md}{\`{}kdb install-\/config-\/file\`{}}} installs or merges configuration files from the file system into Elektra. There is \mbox{\hyperlink{doc_tutorials_install-config-files_md}{a tutorial}} for this tool, too.
\item \`{}kdb cmerge-\/config-\/files\`{} performs a three-\/way merge on three files using Elektra
\end{DoxyEnumerate}\hypertarget{doc_tutorials_cmerge_md_autotoc_md3517}{}\doxysection{Calling the API}\label{doc_tutorials_cmerge_md_autotoc_md3517}
All the tools that use the merge library rely on the same API. An exemplary call to this API can be found in the \href{/home/jenkins/workspace/libelektra-release/examples/kdbset.c}{\texttt{ examples folder}}. 