From 8f15dba8129c4d90f4253841e917222f846953eb Mon Sep 17 00:00:00 2001 From: Mike Farah Date: Wed, 28 Feb 2018 08:07:34 +1100 Subject: [PATCH] Updated docs to explicity put array paths in quotes --- docs/create/index.html | 5 +++-- docs/read/index.html | 11 +++++++---- docs/search/search_index.json | 18 +++++++++--------- docs/sitemap.xml | 12 ++++++------ docs/write/index.html | 8 +++++--- mkdocs/read.md | 7 +++++-- mkdocs/snippets/keys_with_dots.md | 6 ++++-- mkdocs/write.md | 4 +++- 8 files changed, 42 insertions(+), 29 deletions(-) diff --git a/docs/create/index.html b/docs/create/index.html index 916cf58..e93a7fc 100644 --- a/docs/create/index.html +++ b/docs/create/index.html @@ -414,13 +414,14 @@ b.e[0].name: Howdy Partner foo.bar: 7 -
yaml r sample.yaml b[foo.bar]
+
yaml r sample.yaml 'b[foo.bar]'
 

 
-
yaml w sample.yaml b[foo.bar] 9
+
yaml w sample.yaml 'b[foo.bar]' 9
 

 
 
Any valid yaml key can be specified as part of a key lookup.

+
Note that the path is in quotes to avoid the square brackets being interpreted by your shell.

                 
                   
                 
diff --git a/docs/read/index.html b/docs/read/index.html
index a4b8c72..7f7e102 100644
--- a/docs/read/index.html
+++ b/docs/read/index.html
@@ -492,10 +492,11 @@ e.g.: given a sample file of

 

 
 
then

-
yq r sample.yaml b.e[1].name
+
yq r sample.yaml 'b.e[1].name'
 

 
 
will output 'sam'

+
Note that the path is in quotes to avoid the square brackets being interpreted by your shell.

 
Array Splat

 
e.g.: given a sample file of

 
b:
@@ -507,7 +508,7 @@ e.g.: given a sample file of

 

 
 
then

-
yq r sample.yaml b.e[*].name
+
yq r sample.yaml 'b.e[*].name'
 

 
 
will output:

@@ -515,19 +516,21 @@ e.g.: given a sample file of

 - sam
 

 
+
Note that the path is in quotes to avoid the square brackets being interpreted by your shell.

 
Keys with dots

 
When specifying a key that has a dot use key lookup indicator.

 
b:
   foo.bar: 7
 

 
-
yaml r sample.yaml b[foo.bar]
+
yaml r sample.yaml 'b[foo.bar]'
 

 
-
yaml w sample.yaml b[foo.bar] 9
+
yaml w sample.yaml 'b[foo.bar]' 9
 

 
 
Any valid yaml key can be specified as part of a key lookup.

+
Note that the path is in quotes to avoid the square brackets being interpreted by your shell.

                 
                   
                 
diff --git a/docs/search/search_index.json b/docs/search/search_index.json
index 62dff7d..c4ad8b1 100644
--- a/docs/search/search_index.json
+++ b/docs/search/search_index.json
@@ -17,7 +17,7 @@
         },
         {
             "location": "/read/",
-            "text": "yq r  \n\n\n\n\nThis command can take a json file as input too, and will output yaml unless specified to export as json (-j)\n\n\nBasic\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb:\n  c: 2\n\n\n\n\nthen\n\n\nyq r sample.yaml b.c\n\n\n\n\nwill output the value of '2'.\n\n\nFrom Stdin\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\ncat sample.yaml | yq r - b.c\n\n\n\n\nwill output the value of '2'.\n\n\nSplat\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\n---\nbob:\n  item1:\n    cats: bananas\n  item2:\n    cats: apples\n\n\n\n\nthen\n\n\nyq r sample.yaml bob.*.cats\n\n\n\n\nwill output\n\n\n- bananas\n- apples\n\n\n\n\nHandling '.' in the yaml key\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb.x:\n  c: 2\n\n\n\n\nthen\n\n\nyq r sample.yaml \\\"b.x\\\".c\n\n\n\n\nwill output the value of '2'.\n\n\nArrays\n\u00b6\n\n\nYou can give an index to access a specific element:\ne.g.: given a sample file of\n\n\nb:\n  e:\n    - name: fred\n      value: 3\n    - name: sam\n      value: 4\n\n\n\n\nthen\n\n\nyq r sample.yaml b.e[1].name\n\n\n\n\nwill output 'sam'\n\n\nArray Splat\n\u00b6\n\n\ne.g.: given a sample file of\n\n\nb:\n  e:\n    - name: fred\n      value: 3\n    - name: sam\n      value: 4\n\n\n\n\nthen\n\n\nyq r sample.yaml b.e[*].name\n\n\n\n\nwill output:\n\n\n- fred\n- sam\n\n\n\n\nKeys with dots\n\u00b6\n\n\nWhen specifying a key that has a dot use key lookup indicator.\n\n\nb:\n  foo.bar: 7\n\n\n\n\nyaml r sample.yaml b[foo.bar]\n\n\n\n\nyaml w sample.yaml b[foo.bar] 9\n\n\n\n\nAny valid yaml key can be specified as part of a key lookup.",
+            "text": "yq r  \n\n\n\n\nThis command can take a json file as input too, and will output yaml unless specified to export as json (-j)\n\n\nBasic\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb:\n  c: 2\n\n\n\n\nthen\n\n\nyq r sample.yaml b.c\n\n\n\n\nwill output the value of '2'.\n\n\nFrom Stdin\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\ncat sample.yaml | yq r - b.c\n\n\n\n\nwill output the value of '2'.\n\n\nSplat\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\n---\nbob:\n  item1:\n    cats: bananas\n  item2:\n    cats: apples\n\n\n\n\nthen\n\n\nyq r sample.yaml bob.*.cats\n\n\n\n\nwill output\n\n\n- bananas\n- apples\n\n\n\n\nHandling '.' in the yaml key\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb.x:\n  c: 2\n\n\n\n\nthen\n\n\nyq r sample.yaml \\\"b.x\\\".c\n\n\n\n\nwill output the value of '2'.\n\n\nArrays\n\u00b6\n\n\nYou can give an index to access a specific element:\ne.g.: given a sample file of\n\n\nb:\n  e:\n    - name: fred\n      value: 3\n    - name: sam\n      value: 4\n\n\n\n\nthen\n\n\nyq r sample.yaml 'b.e[1].name'\n\n\n\n\nwill output 'sam'\n\n\nNote that the path is in quotes to avoid the square brackets being interpreted by your shell.\n\n\nArray Splat\n\u00b6\n\n\ne.g.: given a sample file of\n\n\nb:\n  e:\n    - name: fred\n      value: 3\n    - name: sam\n      value: 4\n\n\n\n\nthen\n\n\nyq r sample.yaml 'b.e[*].name'\n\n\n\n\nwill output:\n\n\n- fred\n- sam\n\n\n\n\nNote that the path is in quotes to avoid the square brackets being interpreted by your shell.\n\n\nKeys with dots\n\u00b6\n\n\nWhen specifying a key that has a dot use key lookup indicator.\n\n\nb:\n  foo.bar: 7\n\n\n\n\nyaml r sample.yaml 'b[foo.bar]'\n\n\n\n\nyaml w sample.yaml 'b[foo.bar]' 9\n\n\n\n\nAny valid yaml key can be specified as part of a key lookup.\n\n\nNote that the path is in quotes to avoid the square brackets being interpreted by your shell.",
             "title": "Read"
         },
         {
@@ -42,22 +42,22 @@
         },
         {
             "location": "/read/#arrays",
-            "text": "You can give an index to access a specific element:\ne.g.: given a sample file of  b:\n  e:\n    - name: fred\n      value: 3\n    - name: sam\n      value: 4  then  yq r sample.yaml b.e[1].name  will output 'sam'",
+            "text": "You can give an index to access a specific element:\ne.g.: given a sample file of  b:\n  e:\n    - name: fred\n      value: 3\n    - name: sam\n      value: 4  then  yq r sample.yaml 'b.e[1].name'  will output 'sam'  Note that the path is in quotes to avoid the square brackets being interpreted by your shell.",
             "title": "Arrays"
         },
         {
             "location": "/read/#array-splat",
-            "text": "e.g.: given a sample file of  b:\n  e:\n    - name: fred\n      value: 3\n    - name: sam\n      value: 4  then  yq r sample.yaml b.e[*].name  will output:  - fred\n- sam",
+            "text": "e.g.: given a sample file of  b:\n  e:\n    - name: fred\n      value: 3\n    - name: sam\n      value: 4  then  yq r sample.yaml 'b.e[*].name'  will output:  - fred\n- sam  Note that the path is in quotes to avoid the square brackets being interpreted by your shell.",
             "title": "Array Splat"
         },
         {
             "location": "/read/#keys-with-dots",
-            "text": "When specifying a key that has a dot use key lookup indicator.  b:\n  foo.bar: 7  yaml r sample.yaml b[foo.bar]  yaml w sample.yaml b[foo.bar] 9  Any valid yaml key can be specified as part of a key lookup.",
+            "text": "When specifying a key that has a dot use key lookup indicator.  b:\n  foo.bar: 7  yaml r sample.yaml 'b[foo.bar]'  yaml w sample.yaml 'b[foo.bar]' 9  Any valid yaml key can be specified as part of a key lookup.  Note that the path is in quotes to avoid the square brackets being interpreted by your shell.",
             "title": "Keys with dots"
         },
         {
             "location": "/write/",
-            "text": "yq w   \n\n\n\n\nThis command can take a json file as input too, and will output yaml unless specified to export as json (-j)\n\n\nTo Stdout\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb:\n  c: 2\n\n\n\n\nthen\n\n\nyq w sample.yaml b.c cat\n\n\n\n\nwill output:\n\n\nb:\n  c: cat\n\n\n\n\nFrom STDIN\n\u00b6\n\n\ncat sample.yaml | yq w - b.c blah\n\n\n\n\nAdding new fields\n\u00b6\n\n\nAny missing fields in the path will be created on the fly.\n\n\nGiven a sample.yaml file of:\n\n\nb:\n  c: 2\n\n\n\n\nthen\n\n\nyq w sample.yaml b.d[0] \"new thing\"\n\n\n\n\nwill output:\n\n\nb:\n  c: cat\n  d:\n    - new thing\n\n\n\n\nAppending value to an array field\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb:\n  c: 2\n  d:\n    - new thing\n    - foo thing\n\n\n\n\nthen\n\n\nyq w sample.yaml b.d[+] \"bar thing\"\n\n\n\n\nwill output:\n\n\nb:\n  c: cat\n  d:\n    - new thing\n    - foo thing\n    - bar thing\n\n\n\n\nUpdating files in-place\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb:\n  c: 2\n\n\n\n\nthen\n\n\nyq w -i sample.yaml b.c cat\n\n\n\n\nwill update the sample.yaml file so that the value of 'c' is cat.\n\n\nUpdating multiple values with a script\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb:\n  c: 2\n  e:\n    - name: Billy Bob\n\n\n\n\nand a script update_instructions.yaml of:\n\n\nb.c: 3\nb.e[0].name: Howdy Partner\n\n\n\n\nthen\n\n\nyq w -s update_instructions.yaml sample.yaml\n\n\n\n\nwill output:\n\n\nb:\n  c: 3\n  e:\n    - name: Howdy Partner\n\n\n\n\nAnd, of course, you can pipe the instructions in using '-':\n\n\ncat update_instructions.yaml | yq w -s - sample.yaml\n\n\n\n\nValues starting with a hyphen (or dash)\n\u00b6\n\n\nThe flag terminator needs to be used to stop the app from attempting to parse the subsequent arguments as flags:\n\n\nyq w -- my.path -3\n\n\n\n\nwill output\n\n\nmy:\n  path: -3\n\n\n\n\nKeys with dots\n\u00b6\n\n\nWhen specifying a key that has a dot use key lookup indicator.\n\n\nb:\n  foo.bar: 7\n\n\n\n\nyaml r sample.yaml b[foo.bar]\n\n\n\n\nyaml w sample.yaml b[foo.bar] 9\n\n\n\n\nAny valid yaml key can be specified as part of a key lookup.",
+            "text": "yq w   \n\n\n\n\nThis command can take a json file as input too, and will output yaml unless specified to export as json (-j)\n\n\nTo Stdout\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb:\n  c: 2\n\n\n\n\nthen\n\n\nyq w sample.yaml b.c cat\n\n\n\n\nwill output:\n\n\nb:\n  c: cat\n\n\n\n\nFrom STDIN\n\u00b6\n\n\ncat sample.yaml | yq w - b.c blah\n\n\n\n\nAdding new fields\n\u00b6\n\n\nAny missing fields in the path will be created on the fly.\n\n\nGiven a sample.yaml file of:\n\n\nb:\n  c: 2\n\n\n\n\nthen\n\n\nyq w sample.yaml b.d[0] \"new thing\"\n\n\n\n\nwill output:\n\n\nb:\n  c: cat\n  d:\n    - new thing\n\n\n\n\nAppending value to an array field\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb:\n  c: 2\n  d:\n    - new thing\n    - foo thing\n\n\n\n\nthen\n\n\nyq w sample.yaml \"b.d[+]\" \"bar thing\"\n\n\n\n\nwill output:\n\n\nb:\n  c: cat\n  d:\n    - new thing\n    - foo thing\n    - bar thing\n\n\n\n\nNote that the path is in quotes to avoid the square brackets being interpreted by your shell.\n\n\nUpdating files in-place\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb:\n  c: 2\n\n\n\n\nthen\n\n\nyq w -i sample.yaml b.c cat\n\n\n\n\nwill update the sample.yaml file so that the value of 'c' is cat.\n\n\nUpdating multiple values with a script\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb:\n  c: 2\n  e:\n    - name: Billy Bob\n\n\n\n\nand a script update_instructions.yaml of:\n\n\nb.c: 3\nb.e[0].name: Howdy Partner\n\n\n\n\nthen\n\n\nyq w -s update_instructions.yaml sample.yaml\n\n\n\n\nwill output:\n\n\nb:\n  c: 3\n  e:\n    - name: Howdy Partner\n\n\n\n\nAnd, of course, you can pipe the instructions in using '-':\n\n\ncat update_instructions.yaml | yq w -s - sample.yaml\n\n\n\n\nValues starting with a hyphen (or dash)\n\u00b6\n\n\nThe flag terminator needs to be used to stop the app from attempting to parse the subsequent arguments as flags:\n\n\nyq w -- my.path -3\n\n\n\n\nwill output\n\n\nmy:\n  path: -3\n\n\n\n\nKeys with dots\n\u00b6\n\n\nWhen specifying a key that has a dot use key lookup indicator.\n\n\nb:\n  foo.bar: 7\n\n\n\n\nyaml r sample.yaml 'b[foo.bar]'\n\n\n\n\nyaml w sample.yaml 'b[foo.bar]' 9\n\n\n\n\nAny valid yaml key can be specified as part of a key lookup.\n\n\nNote that the path is in quotes to avoid the square brackets being interpreted by your shell.",
             "title": "Write/Update"
         },
         {
@@ -77,7 +77,7 @@
         },
         {
             "location": "/write/#appending-value-to-an-array-field",
-            "text": "Given a sample.yaml file of:  b:\n  c: 2\n  d:\n    - new thing\n    - foo thing  then  yq w sample.yaml b.d[+] \"bar thing\"  will output:  b:\n  c: cat\n  d:\n    - new thing\n    - foo thing\n    - bar thing",
+            "text": "Given a sample.yaml file of:  b:\n  c: 2\n  d:\n    - new thing\n    - foo thing  then  yq w sample.yaml \"b.d[+]\" \"bar thing\"  will output:  b:\n  c: cat\n  d:\n    - new thing\n    - foo thing\n    - bar thing  Note that the path is in quotes to avoid the square brackets being interpreted by your shell.",
             "title": "Appending value to an array field"
         },
         {
@@ -97,12 +97,12 @@
         },
         {
             "location": "/write/#keys-with-dots",
-            "text": "When specifying a key that has a dot use key lookup indicator.  b:\n  foo.bar: 7  yaml r sample.yaml b[foo.bar]  yaml w sample.yaml b[foo.bar] 9  Any valid yaml key can be specified as part of a key lookup.",
+            "text": "When specifying a key that has a dot use key lookup indicator.  b:\n  foo.bar: 7  yaml r sample.yaml 'b[foo.bar]'  yaml w sample.yaml 'b[foo.bar]' 9  Any valid yaml key can be specified as part of a key lookup.  Note that the path is in quotes to avoid the square brackets being interpreted by your shell.",
             "title": "Keys with dots"
         },
         {
             "location": "/create/",
-            "text": "Yaml files can be created using the 'new' command. This works in the same way as the write command, but you don't pass in an existing Yaml file.\n\n\nyq n  \n\n\n\n\nCreating a simple yaml file\n\u00b6\n\n\nyq n b.c cat\n\n\n\n\nwill output:\n\n\nb:\n  c: cat\n\n\n\n\nCreating using a create script\n\u00b6\n\n\nCreate scripts follow the same format as the update scripts.\n\n\nGiven a script create_instructions.yaml of:\n\n\nb.c: 3\nb.e[0].name: Howdy Partner\n\n\n\n\nthen\n\n\nyq n -s create_instructions.yaml\n\n\n\n\nwill output:\n\n\nb:\n  c: 3\n  e:\n    - name: Howdy Partner\n\n\n\n\nYou can also pipe the instructions in:\n\n\ncat create_instructions.yaml | yq n -s -\n\n\n\n\nKeys with dots\n\u00b6\n\n\nWhen specifying a key that has a dot use key lookup indicator.\n\n\nb:\n  foo.bar: 7\n\n\n\n\nyaml r sample.yaml b[foo.bar]\n\n\n\n\nyaml w sample.yaml b[foo.bar] 9\n\n\n\n\nAny valid yaml key can be specified as part of a key lookup.",
+            "text": "Yaml files can be created using the 'new' command. This works in the same way as the write command, but you don't pass in an existing Yaml file.\n\n\nyq n  \n\n\n\n\nCreating a simple yaml file\n\u00b6\n\n\nyq n b.c cat\n\n\n\n\nwill output:\n\n\nb:\n  c: cat\n\n\n\n\nCreating using a create script\n\u00b6\n\n\nCreate scripts follow the same format as the update scripts.\n\n\nGiven a script create_instructions.yaml of:\n\n\nb.c: 3\nb.e[0].name: Howdy Partner\n\n\n\n\nthen\n\n\nyq n -s create_instructions.yaml\n\n\n\n\nwill output:\n\n\nb:\n  c: 3\n  e:\n    - name: Howdy Partner\n\n\n\n\nYou can also pipe the instructions in:\n\n\ncat create_instructions.yaml | yq n -s -\n\n\n\n\nKeys with dots\n\u00b6\n\n\nWhen specifying a key that has a dot use key lookup indicator.\n\n\nb:\n  foo.bar: 7\n\n\n\n\nyaml r sample.yaml 'b[foo.bar]'\n\n\n\n\nyaml w sample.yaml 'b[foo.bar]' 9\n\n\n\n\nAny valid yaml key can be specified as part of a key lookup.\n\n\nNote that the path is in quotes to avoid the square brackets being interpreted by your shell.",
             "title": "Create"
         },
         {
@@ -117,7 +117,7 @@
         },
         {
             "location": "/create/#keys-with-dots",
-            "text": "When specifying a key that has a dot use key lookup indicator.  b:\n  foo.bar: 7  yaml r sample.yaml b[foo.bar]  yaml w sample.yaml b[foo.bar] 9  Any valid yaml key can be specified as part of a key lookup.",
+            "text": "When specifying a key that has a dot use key lookup indicator.  b:\n  foo.bar: 7  yaml r sample.yaml 'b[foo.bar]'  yaml w sample.yaml 'b[foo.bar]' 9  Any valid yaml key can be specified as part of a key lookup.  Note that the path is in quotes to avoid the square brackets being interpreted by your shell.",
             "title": "Keys with dots"
         },
         {
diff --git a/docs/sitemap.xml b/docs/sitemap.xml
index 95a6334..1fb0779 100644
--- a/docs/sitemap.xml
+++ b/docs/sitemap.xml
@@ -4,7 +4,7 @@
     
     
      /
-     2018-02-19
+     2018-02-28
      daily
     
     
@@ -12,7 +12,7 @@
     
     
      /read/
-     2018-02-19
+     2018-02-28
      daily
     
     
@@ -20,7 +20,7 @@
     
     
      /write/
-     2018-02-19
+     2018-02-28
      daily
     
     
@@ -28,7 +28,7 @@
     
     
      /create/
-     2018-02-19
+     2018-02-28
      daily
     
     
@@ -36,7 +36,7 @@
     
     
      /convert/
-     2018-02-19
+     2018-02-28
      daily
     
     
@@ -44,7 +44,7 @@
     
     
      /merge/
-     2018-02-19
+     2018-02-28
      daily
     
     
diff --git a/docs/write/index.html b/docs/write/index.html
index f960f1c..2e4d65a 100644
--- a/docs/write/index.html
+++ b/docs/write/index.html
@@ -494,7 +494,7 @@
 

 
 
then

-
yq w sample.yaml b.d[+] "bar thing"
+
yq w sample.yaml "b.d[+]" "bar thing"
 

 
 
will output:

@@ -506,6 +506,7 @@
     - bar thing
 

 
+
Note that the path is in quotes to avoid the square brackets being interpreted by your shell.

 
Updating files in-place

 
Given a sample.yaml file of:

 
b:
@@ -561,13 +562,14 @@ b.e[0].name: Howdy Partner
   foo.bar: 7
 

 
-
yaml r sample.yaml b[foo.bar]
+
yaml r sample.yaml 'b[foo.bar]'
 

 
-
yaml w sample.yaml b[foo.bar] 9
+
yaml w sample.yaml 'b[foo.bar]' 9
 

 
 
Any valid yaml key can be specified as part of a key lookup.

+
Note that the path is in quotes to avoid the square brackets being interpreted by your shell.

                 
                   
                 
diff --git a/mkdocs/read.md b/mkdocs/read.md
index 8cf7d62..27a8d9a 100644
--- a/mkdocs/read.md
+++ b/mkdocs/read.md
@@ -68,10 +68,12 @@ b:
 ```
 then
 ```
-yq r sample.yaml b.e[1].name
+yq r sample.yaml 'b.e[1].name'
 ```
 will output 'sam'
 
+Note that the path is in quotes to avoid the square brackets being interpreted by your shell.
+
 ### Array Splat
 e.g.: given a sample file of
 ```yaml
@@ -84,12 +86,13 @@ b:
 ```
 then
 ```
-yq r sample.yaml b.e[*].name
+yq r sample.yaml 'b.e[*].name'
 ```
 will output:
 ```
 - fred
 - sam
 ```
+Note that the path is in quotes to avoid the square brackets being interpreted by your shell.
 
 {!snippets/keys_with_dots.md!}
diff --git a/mkdocs/snippets/keys_with_dots.md b/mkdocs/snippets/keys_with_dots.md
index 81f8f18..76c084b 100644
--- a/mkdocs/snippets/keys_with_dots.md
+++ b/mkdocs/snippets/keys_with_dots.md
@@ -7,11 +7,13 @@ b:
 ```
 
 ```bash
-yaml r sample.yaml b[foo.bar]
+yaml r sample.yaml 'b[foo.bar]'
 ```
 
 ```bash
-yaml w sample.yaml b[foo.bar] 9
+yaml w sample.yaml 'b[foo.bar]' 9
 ```
 
 Any valid yaml key can be specified as part of a key lookup.
+
+Note that the path is in quotes to avoid the square brackets being interpreted by your shell.
diff --git a/mkdocs/write.md b/mkdocs/write.md
index a96079d..4edb186 100644
--- a/mkdocs/write.md
+++ b/mkdocs/write.md
@@ -55,7 +55,7 @@ b:
 ```
 then
 ```bash
-yq w sample.yaml b.d[+] "bar thing"
+yq w sample.yaml "b.d[+]" "bar thing"
 ```
 will output:
 ```yaml
@@ -67,6 +67,8 @@ b:
     - bar thing
 ```
 
+Note that the path is in quotes to avoid the square brackets being interpreted by your shell.
+
 ### Updating files in-place
 Given a sample.yaml file of:
 ```yaml