yaml merge Examples

1. Introduction
2. Simple Example
   1. Whole File Merge
   2. Document Fragment Merge
   3. CLI-Supplied Data

Introduction

This page explores various real-world use-cases for the yaml-merge command-line tool.

Simple Example

Document: LHS.yaml

---
deep:
  hash:
    structure:
      key: value
      leave: intact

There are a few ways to change value to New Value. You could just use the yaml-set command rather than yaml-merge, like so: yaml-set --change=/deep/hash/structure/key --value='New Value' LHS.yaml

But what if you don't want LHS.yaml to be modified, or you want the changed document on STDOUT, say to feed into a subsequent piped command? This is where yaml-merge can help and there are multiple ways to solve these questions. These include:

1. Whole file merge where the RHS document contains the minimum data structure necessary to indicate where with the LHS document its data is to be merged.
2. File fragment merge where only the desired RHS data is written and a --mergeat (-m) indicates where within the LHS document this RHS data is to be merged.
3. CLI-supplied merge data where only the desired RHS data is fed to yaml-merge via STDIN and a --mergeat (-m) indicates where within the LHS document this RHS data is to be merged. The RHS data can be a proper YAML document, a proper JSON string, or a Python JSON-like string (without all the quoting of proper JSON).

The following sections demonstrate all three approaches.

Whole File Merge

You could create a complete RHS document as an entirely new YAML file, like this:

Document: RHS-FULL.yaml

---
deep:
  hash:
    structure:
      key: New Value

To merge these two documents together, you'd simply execute: yaml-merge LHS.yaml RHS-FULL.yaml

While this would generate the desired outcome, far more complex LHS structures could be not only tedious, but also error-prone to build up a sufficient RHS document to affect the desired alteration.

Document Fragment Merge

You could supply a document fragment for the RHS, like so:

Document: RHS-FRAGMENT.yaml

---
key: New Value

To merge the fragment into the whole, execute: yaml-merge --mergeat=/deep/hash/structure LHS.yaml RHS-FRAGMENT.yaml

CLI-Supplied Data

You could spare all versions of the RHS file and instead use STDIN to emulate a yaml-set call via yaml-merge to get the same outcome: echo 'New Value' | yaml-merge --mergeat=/deep/hash/structure/key LHS.yaml -

Notice that only the actual Scalar data was provided in this case because for this example, we were only trying to change a single String value. You could provide the key-value pair of the destination and shorten the merge target path, like so: echo '{key: New Value}' | yaml-merge --mergeat=/deep/hash/structure LHS.yaml -

And naturally, any amount of the RHS can be provided as long as the supplied YAML Path places it precisely where you want it to be merged. For example:

echo '{structure: {key: New Value}}' | \
  yaml-merge --mergeat=/deep/hash LHS.yaml -`

And so on.