yaml merge Configuration File

1. Introduction
2. Cautions

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 accepts configuration in the form of command-line arguments and an INI-style configuration file. Users instruct yaml-merge to read from their configuration file via the --config or -c command-line argument.

A configuration file for the yaml-merge command supports these sections:

1. [defaults] controls overarching (default) modes for the various merge categories.
2. [rules] specifies YAML Paths and the merge mode to be applied to that node and its child nodes (unless overridden by another rule).
3. [keys] defines identity key fields for Arrays-of-Hashes (AoHs) within the merge data.

These sections are discussed with examples on the pages for each of the various types of data entities which yaml-merge handles:

• Arrays
• Hashes
• Arrays-of-Hashes
• Anchors

Cautions

There is some potential for issues with this configuration file. These include:

1. While the 3rd-Party Library used by yaml-merge to read user-specified configuration files can support : as a delimiter between each key and its value, use =, instead. Should any configuration line contain multiple = symbols, it will still be correctly utilized by yaml-merge. The same is not true should any line contain more than one :.
2. All [rules] and [keys] are applied only to Right-Hand-Side (RHS) documents during the merge process. Any rules created which would target only elements in the left-most document will have no effect during a merge.
3. The order of YAML Paths within the [rules] and [keys] sections from top-down is important. Later defined rules or keys override earlier definitions should any two entries target the same nodes within the merge documents.
4. Be particularly mindful of which nodes get targeted by YAML Paths within the [rules] section and which merge mode gets applied to them. Some data element merge modes are incompatible with nodes of the wrong data-type and will cause an error when improperly applied. For example, the deep mode that is shared between Hash and Array-of-Hash nodes is incompatible with Array nodes. Likewise, unique works with Array and Array-of-Hashes nodes but not Hash nodes.