$darkmode
Elektra 0.11.0
|
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 KeySets from the kdb
tool.
The command to use this tool is:
The standard naming scheme for a three-way merge consists of ours
, theirs
, and base
:
ours
refers to the local copy of a filetheirs
refers to a remote copybase
refers to their common ancestor.This works very similarly for KeySets, especially ones that consist of mounted configuration files.
For mounted configuration files:
ours
should be the user's copytheirs
would be the maintainers copy,base
would be the previous version of the maintainer's copy.If the user is just trying to accomplish 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 KeySet. In kdb merge
, ourpath
, theirpath
, and basepath
work just like ours
, theirs
, and base
except each one represents the root of a KeySet. The argument 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 consequences.
As for the options, there are two basic options:
-i
, --interactive
: which attempts the merge in an interactive way-f
, --force
: which overwrites any Keys in resultpath
Additionally, there is an option to specify a merge strategy, which is very important.
The option for strategy is:
-s <name>
, --strategy <name>
: which is used to specify a strategy to use in case of a conflictThe current list of strategies are:
preserve
: the merge will fail if a conflict is detectedours
: the merge will use our version during a conflicttheirs
: the merge will use their version during a conflictcut
: Removes existing keys below the resultpath and replaces them with the merged keyset.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.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
, cut
or import
) for the resulting Key.
Basic Usage:
Here are examples of the same KeySets being merged using different strategies. The KeySets are mounted using a property format, the left side of '=' is the name of the Key, the right side is its string value.
We start with the base KeySet, system:/base
:
Here is our KeySet, system:/ours
:
Here is their KeySet, system:/theirs
:
To add the keys to the key database, execute the following commands:
Now we will examine the result KeySet with the different strategies.
The merge will fail because of a conflict for key4
since key4
was deleted in our KeySet and edited in their KeySet. Since we used preserve, the merge fails and the result KeySet is not saved.
The result KeySet, user:/tests/result
will be:
The values of the keys are:
The conflict of key4
(it was deleted in ours
but changed in theirs
) is solved by using our copy, thus deleting the key.
Now we delete the result keys and try the next merging strategy.
The result KeySet, user:/tests/result
will be:
The values of the keys are:
Here, the conflict of key4
is solved by using their copy, thus key4=banana
.
We delete the result keys again and finally try the cut
merging strategy.
The result KeySet, user:/tests/result
will be:
The values of the keys are:
Here the state of theirs is simply copied to the resultpath
.