yaml merge Array Options

1. Introduction
2. Merging All Elements Together
3. Block RHS Elements
4. Overwrite LHS Arrays
5. Accept Only Unique Elements
6. Configuration File Options
   1. Configuration File Section: defaults
   2. Configuration File Section: rules

This document is part of the body of knowledge about yaml-merge, one of the reference command-line tools provided by the YAML Path project.

Introduction

The yaml-merge command-line tool enables users to control how it merges Arrays (AKA Lists or Sequences). This is different from merging Arrays-of-Hashes, discussed elsewhere. By default, every Array element in the RHS document will be appended to LHS Arrays at the same location. The available Array merge options include:

1. all (the default) is as described above; every element is appended from the RHS document to the LHS document.
2. left causes RHS Arrays to be ignored when an Array already exists at the same location within the LHS document. RHS Arrays are retained only where there is no LHS Array at the same location.
3. right causes LHS Arrays to be entirely replaced by the RHS Array when an Array exists at the same location within both documents. LHS Arrays are retained only where there is no RHS Array at the same location.
4. unique ignores RHS Array elements which already exist within the LHS Array, appending the rest.

Each of these options will be explored in the following sections. All sections will use these two documents for their discussions:

File: LHS.yaml

---
strings:
  - one
  - two
integers:
  - 1
  - 2
lhs_exclusive:
  - true

File: RHS.yaml

---
strings:
  - two
  - three
integers:
  - 2
  - 3
rhs_exclusive:
  - true

Merging All Elements Together

This is the default mode and ensures that every Array element from every merge document is retained, including duplicates. When the two example documents are merged with --arrays=all or -A all, the resulting document becomes:

---
strings:
  - one
  - two
  - two
  - three
integers:
  - 1
  - 2
  - 2
  - 3
lhs_exclusive:
  - true
rhs_exclusive:
  - true

Block RHS Elements

Should you need to retain only LHS elements, blocking all RHS elements from Arrays at the same location within the YAML documents, use --arrays=left or -A left. Doing so produces this result from the example documents:

---
strings:
  - one
  - two
integers:
  - 1
  - 2
lhs_exclusive:
  - true
rhs_exclusive:
  - true

Notice that only the rhs_exclusive Array in RHS.yaml was retained from the RHS document.

Overwrite LHS Arrays

Should you need to completely overwrite preexisting Array elements in the LHS document, retaining only LHS Arrays with no Arrays in the RHS document at the same locations, use --arrays=right or -A right. Doing so produces this result from the example documents:

---
strings:
  - two
  - three
integers:
  - 2
  - 3
lhs_exclusive:
  - true
rhs_exclusive:
  - true

Notice that the only Array from LHS.yaml to survive the merge was that in lhs_exclusive.

Accept Only Unique Elements

When you need to merge only Array elements which do not already exist within the LHS Arrays, use --arrays=unique or -A unique. Merging the example documents with this option yields:

---
strings:
  - one
  - two
  - three
integers:
  - 1
  - 2
  - 3
lhs_exclusive:
  - true
rhs_exclusive:
  - true

Notice that all duplicate Array elements from the RHS document were discarded during the merge.

Configuration File Options

The yaml-merge tool can read per YAML Path merging options from an INI-Style configuration file via its --config (-c) argument. Whereas the --arrays (-A) argument supplies an overarching mode for merging Arrays, using a configuration file permits far more precise control whenever you need a different mode for specific parts of the merge documents.

Configuration File Section: defaults

The [defaults] section permits a key named, arrays, which behaves identically to the --arrays (-A) command-line argument to the yaml-merge tool. The [defaults]arrays setting is overridden by the same-named command-line argument, when supplied. In practice, this file may look like:

File merge-options.ini

[defaults]
arrays = all

Note the spaces around the = sign are optional but only an = sign may be used to separate each key from its value.

Configuration File Section: rules

The [rules] section takes any YAML Paths as keys and any of the Array merge modes that are available to the --arrays (-A) command-line argument. This enables extremely fine precision for applying the available modes.

Using the same two documents as all prior examples, adding a configuration file with these contents:

[rules]
/strings = left
/integers = right

... would produce this merged document:

---
strings:
  - one
  - two
integers:
  - 2
  - 3
lhs_exclusive:
  - true
rhs_exclusive:
  - true

Notice the following:

1. The Array at /strings retained only elements from LHS.yaml due to the INI-defined rule which applied to it: left.
2. The Array at /integers was wholly overwritten by the elements from RHS.yaml due to the INI-defined rule which applied to it: right.