Skip to content

Latest commit

 

History

History
99 lines (64 loc) · 3.25 KB

kdb-cmerge.md

File metadata and controls

99 lines (64 loc) · 3.25 KB

kdb-cmerge(1) -- Three-way merge of KeySets

NAME

kdb-cmerge - Join three key sets together

SYNOPSIS

kdb cmerge [OPTIONS] our their base result

  • ourpath: Path to the keyset to serve as our

  • theirpath: path to the keyset to serve as their

  • basepath: path to the base keyset

  • resultpath: path without keys where the merged keyset will be saved

DESCRIPTION

kdb cmerge can incorporate changes from two modified versions (our and their) into a common preceding version (base) of a key set. This lets you merge the sets of changes represented by the two newer key sets. This is called a three-way merge between key sets.
On success the resulting keyset will be saved to mergepath.
On unresolved conflicts nothing will be changed.
This tool currently exists alongside kdb merge until it is completely ready to supersede it. At this moment, cmerge will be renamed to merge.

OPTIONS

The options of kdb cmerge are:

  • -f, --force: overwrite existing keys in result
  • -v, --verbose: give additional information

Strategies offer fine grained control over conflict handling. The option is:

  • -s <name>, --strategy <name>: which is used to specify a strategy to use in case of a conflict

Strategies have their own man page which can be accessed with man elektra-cmerge-strategies.

RETURN VALUE

  • 0: Successful.

  • 11: An error happened.

  • 12: A merge conflict occurred and merge strategy abort was set.

The result of the merge is stored in result.

THREE-WAY MERGE

You can think of the three-way merge as subtracting base from their and adding the result to our, or as merging into our the changes that would turn base into their. Thus, it behaves exactly as the GNU diff3 tool. These three versions of the KeySet are:

  • base: The base KeySet is the original version of the key set.

  • our: The our KeySet represents the user's current version of the KeySet.
    This KeySet differs from base for every key you changed.

  • their: The their KeySet usually represents the default version of a KeySet (usually the package maintainer's version).
    This KeySet differs from base for every key someone has changed.

The three-way merge works by comparing the our KeySet and the their KeySet to the base KeySet. By looking for differences in these KeySets, a new KeySet called result is created that represents a merge of these KeySets.

CONFLICTS

Conflicts occur when a key has a different value in all three key sets or when only base differs. When all three values for a key differ, we call this an overlap. Different merge strategies exist to resolve those conflicts.

EXAMPLES

To complete a simple merge of three KeySets:

kdb set user:/base "A"
#> Create a new key user:/base with string "A"
kdb set user:/their "A"
#> Create a new key user:/their with string "A"
kdb set user:/our "B"
#> Create a new key user:/our with string "B"
kdb cmerge user:/our user:/their user:/base user:/result
kdb get user:/result
#>B

```<br>

## SEE ALSO

- [elektra-cmerge-strategy(7)](elektra-cmerge-strategy.md)
- [elektra-key-names(7)](elektra-key-names.md) for an explanation of key names.