yaml merge Anchor Options

1. Introduction

Introduction

The yaml-merge command-line tool enables users to control how it handle conflicting Anchors during a merge operation. Non-conflicting Anchors are automatically merged and the definition-use order between each Anchor and its Aliases is preserved during the merge. An Anchor conflict occurs only when the same Anchor name is used in both of the LHS and RHS documents and the Anchored value is different between them.

But what are Anchors? In short:

Anchors are a name assigned to a Scalar or Hash YAML data element. This name is prefixed with an & sign. Beyond that point within the YAML data, the data which was "anchored" can be re-used any number of times by referencing the Anchor via its Alias form whereby the & is replaced with an * sign.

In other words, YAML defines two kinds of Anchors. Scalar Anchors define reusable Scalar values (which are String, Integer, Float, Boolean, etc. data types). Hash Anchors (AKA Map Anchors or Dictionary Anchors). To date, there is no definition in YAML for an Array Anchor (AKA List Anchor AKA Sequence Anchor).

Each of these Anchor types will be explored in how they are merged based on user option selection. When there is no conflict, RHS Anchors are merged into the LHS document no matter what Anchor merge option is selected. In order to resolve Anchor conflicts, the yaml-merge tool's available Anchor merge options include:

1. stop (the default) causes merging to abort upon detection of an Anchor conflict.
2. left causes LHS Anchors to overwrite conflicting RHS Anchors.
3. right causes RHS Anchors to overwrite conflicting LHS Anchors.
4. rename causes RHS Anchors to be automatically and uniquely renamed before they are merged into the LHS document.

Scalar Anchors

Scalar Anchors are usually gathered up into a special Array named aliases: near the top of each YAML file. Such a file might look like:

---
aliases:
  - &scalar_anchor_string This is a reusable String value
  - &scalar_anchor_integer 5280

a_hash:
  which_reuses:
    those_anchors:
      string_alias: *scalar_anchor_string
      integer_alias: *scalar_anchor_integer
  in_several_places:
    string_alias: *scalar_anchor_string
    integer_alias: *scalar_anchor_integer