From cd3813e285543fb9ef5acf068db6e4a8397fc8b8 Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Sun, 5 Dec 2021 11:11:59 +1100
Subject: [PATCH] Improved tips and tricks

---
 operators/sort-keys.md   |  8 ++++----
 usage/tips-and-tricks.md | 19 ++++++++++++-------
 2 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/operators/sort-keys.md b/operators/sort-keys.md
index e8f4d6dc..c0a283df 100644
--- a/operators/sort-keys.md
+++ b/operators/sort-keys.md
@@ -5,8 +5,8 @@ The Sort Keys operator sorts maps by their keys (based on their string value). T
 Sort is particularly useful for diffing two different yaml documents:
 
 ```bash
-yq eval -i 'sortKeys(..)' file1.yml
-yq eval -i 'sortKeys(..)' file2.yml
+yq eval -i -P 'sort_keys(..)' file1.yml
+yq eval -i -P 'sort_keys(..)' file2.yml
 diff file1.yml file2.yml
 ```
 
@@ -19,7 +19,7 @@ b: bing
 ```
 then
 ```bash
-yq eval 'sortKeys(.)' sample.yml
+yq eval 'sort_keys(.)' sample.yml
 ```
 will output
 ```yaml
@@ -49,7 +49,7 @@ aParent:
 ```
 then
 ```bash
-yq eval 'sortKeys(..)' sample.yml
+yq eval 'sort_keys(..)' sample.yml
 ```
 will output
 ```yaml
diff --git a/usage/tips-and-tricks.md b/usage/tips-and-tricks.md
index fa852511..3df31027 100644
--- a/usage/tips-and-tricks.md
+++ b/usage/tips-and-tricks.md
@@ -8,16 +8,18 @@ Yaml files can be surprisingly lenient in what can be parsed as a yaml file. A r
 yq e --exit-status 'tag == "!!map" or tag== "!!seq"' file.txt > /dev/null
 ```
 
-## Split expressions over multiple lines to improve readablity
+## Split expressions over multiple lines to improve readability
 
 Feel free to use multiple lines in your expression to improve readability.
 
+Use `with` if you need to make several updates to the same path.
+
 ```bash
 yq eval --inplace '
-  .a.b.c[0].frog = "thingo" |
-  .a.b.c[0].frog style= "double" |
-  .different.path.somehere = "foo" |
-  .different.path.somehere style= "folded"
+  with(.a.deeply.nested; 
+    . = "newValue" | . style="single") |
+  with(.b.another.nested; 
+    . = "cool" | . style="folded")
 ' my_file.yaml
 ```
 
@@ -93,10 +95,12 @@ yq e -n '.someNew="content"' > newfile.yml
 The best way to run a diff is to use `yq` to normalise the yaml files and then just use diff. Here is a simple example of using pretty print `-P` to normalise the styling and running diff:
 
 ```
-diff <(yq e -P examples/data1.yaml) <(yq e -P examples/data2.yaml)
+diff <(yq e -P 'sort_keys(..)' examples/data1.yaml) <(yq e -P 'sort_keys(..)' examples/data2.yaml)
 ```
 
-This way you can use the full power of `diff` and normalise the yaml files as you like - for instance you may also want to remove all comments using `... comments=""`
+This way you can use the full power of `diff` and normalise the yaml files as you like.
+
+You may also want to remove all comments using `... comments=""`
 
 ## Reading multiple streams (STDINs)
 
@@ -107,6 +111,7 @@ yq e '.apple' <(curl -s https://somewhere/data1.yaml) <(cat file.yml)
 ```
 
 ## Updating deeply selected paths
+### or why is yq only returning the updated yaml
 
 The most important thing to remember to do is to have brackets around the LHS expression - otherwise what `yq` will do is first filter by the selection, and then, separately, update the filtered result and return that subset.