From e402e47522db3119ad90966c2038bbfff625c0bf Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Sun, 20 Mar 2022 13:05:09 +1100
Subject: [PATCH] v4.23.1

---
 operators/env-variable-operators.md | 100 +++++++++++++++++++++++++++-
 operators/equals.md                 |   4 +-
 operators/multiply-merge.md         |  11 ++-
 3 files changed, 110 insertions(+), 5 deletions(-)

diff --git a/operators/env-variable-operators.md b/operators/env-variable-operators.md
index b8adf077..a3973023 100644
--- a/operators/env-variable-operators.md
+++ b/operators/env-variable-operators.md
@@ -3,11 +3,24 @@
 These operators are used to handle environment variables usage in expressions and documents. While environment variables can, of course, be passed in via your CLI with string interpolation, this often comes with complex quote escaping and can be tricky to write and read. 
 
 There are three operators:
+
 -  `env` which takes a single environment variable name and parse the variable as a yaml node (be it a map, array, string, number of boolean) 
 - `strenv` which also takes a single environment variable name, and always parses the variable as a string.
 - `envsubst` which you pipe strings into and it interpolates environment variables in strings using [envsubst](https://github.com/a8m/envsubst). 
 
 
+## EnvSubst Options
+You can optionally pass envsubst any of the following options:
+
+  - nu: NoUnset, this will fail if there are any referenced variables that are not set
+  - ne: NoEmpty, this will fail if there are any referenced variables that are empty
+  - ff: FailFast, this will abort on the first failure (rather than collect all the errors)
+
+E.g:
+`envsubst(ne, ff)` will fail on the first empty variable.
+
+See [Imposing Restrictions](https://github.com/a8m/envsubst#imposing-restrictions) in the `envsubst` documentation for more information, and below for examples.
+
 ## Tip
 To replace environment variables across all values in a document, `envsubst` can be used with the recursive descent operator
 as follows:
@@ -133,23 +146,83 @@ the cat meows
 ## Replace strings with envsubst, missing variables
 Running
 ```bash
-myenv="cat" yq --null-input '"the ${myenvnonexisting} meows" | envsubst'
+yq --null-input '"the ${myenvnonexisting} meows" | envsubst'
 ```
 will output
 ```yaml
 the  meows
 ```
 
+## Replace strings with envsubst(nu), missing variables
+(nu) not unset, will fail if there are unset (missing) variables
+
+Running
+```bash
+yq --null-input '"the ${myenvnonexisting} meows" | envsubst(nu)'
+```
+will output
+```bash
+Error: variable ${myenvnonexisting} not set
+```
+
+## Replace strings with envsubst(ne), missing variables
+(ne) not empty, only validates set variables
+
+Running
+```bash
+yq --null-input '"the ${myenvnonexisting} meows" | envsubst(ne)'
+```
+will output
+```yaml
+the  meows
+```
+
+## Replace strings with envsubst(ne), empty variable
+(ne) not empty, will fail if a references variable is empty
+
+Running
+```bash
+myenv="" yq --null-input '"the ${myenv} meows" | envsubst(ne)'
+```
+will output
+```bash
+Error: variable ${myenv} set but empty
+```
+
 ## Replace strings with envsubst, missing variables with defaults
 Running
 ```bash
-myenv="cat" yq --null-input '"the ${myenvnonexisting-dog} meows" | envsubst'
+yq --null-input '"the ${myenvnonexisting-dog} meows" | envsubst'
 ```
 will output
 ```yaml
 the dog meows
 ```
 
+## Replace strings with envsubst(nu), missing variables with defaults
+Having a default specified skips over the missing variable.
+
+Running
+```bash
+yq --null-input '"the ${myenvnonexisting-dog} meows" | envsubst(nu)'
+```
+will output
+```yaml
+the dog meows
+```
+
+## Replace strings with envsubst(ne), missing variables with defaults
+Fails, because the variable is explicitly set to blank.
+
+Running
+```bash
+myEmptyEnv="" yq --null-input '"the ${myEmptyEnv-dog} meows" | envsubst(ne)'
+```
+will output
+```bash
+Error: variable ${myEmptyEnv} set but empty
+```
+
 ## Replace string environment variable in document
 Given a sample.yml file of:
 ```yaml
@@ -164,3 +237,26 @@ will output
 v: cat meow
 ```
 
+## (Default) Return all envsubst errors
+By default, all errors are returned at once.
+
+Running
+```bash
+yq --null-input '"the ${notThere} ${alsoNotThere}" | envsubst(nu)'
+```
+will output
+```bash
+Error: variable ${notThere} not set
+variable ${alsoNotThere} not set
+```
+
+## Fail fast, return the first envsubst error (and abort)
+Running
+```bash
+yq --null-input '"the ${notThere} ${alsoNotThere}" | envsubst(nu,ff)'
+```
+will output
+```bash
+Error: variable ${notThere} not set
+```
+
diff --git a/operators/equals.md b/operators/equals.md
index e15b6a27..d108c9f0 100644
--- a/operators/equals.md
+++ b/operators/equals.md
@@ -1,4 +1,4 @@
-# Equals
+# Equals / Not Equals
 
 This is a boolean operator that will return `true` if the LHS is equal to the RHS and `false` otherwise.
 
@@ -12,6 +12,8 @@ It is most often used with the select operator to find particular nodes:
 select(.a == .b)
 ```
 
+The not equals `!=` operator returns `false` if the LHS is equal to the RHS.
+
 {% hint style="warning" %}
 Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
 
diff --git a/operators/multiply-merge.md b/operators/multiply-merge.md
index 20bbd968..f2a3fb52 100644
--- a/operators/multiply-merge.md
+++ b/operators/multiply-merge.md
@@ -15,11 +15,18 @@ You can control how objects are merged by using one or more of the following fla
 - `?` only merge _existing_ fields
 - `n` only merge _new_ fields
 
-### Merging files
+
+### Merge two files together
+This uses the load operator to merge file2 into file1.
+```bash
+yq '. *= load("file2.yml")' file1.yml
+```
+
+### Merging all files
 Note the use of `eval-all` to ensure all documents are loaded into memory.
 
 ```bash
-yq eval-all 'select(fileIndex == 0) * select(fileIndex == 1)' file1.yaml file2.yaml
+yq eval-all '. as $item ireduce ({}; . * $item )' *.yml
 ```
 
 {% hint style="warning" %}