From 6e35356a847bc66076ab7bb8aefd94116dd68214 Mon Sep 17 00:00:00 2001 From: Georgi Knox Date: Tue, 14 May 2019 13:28:06 -0400 Subject: [PATCH] add help description --- README.md | 10 ++++++---- commands_test.go | 15 +++++++++++++-- docs/search/search_index.json | 2 +- docs/sitemap.xml | 16 ++++++++-------- docs/sitemap.xml.gz | Bin 200 -> 201 bytes yq.go | 4 +++- 6 files changed, 31 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index a9d9472a..e56c9cb3 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# yq +# yq [![Build Status](https://travis-ci.org/mikefarah/yq.svg?branch=master)](https://travis-ci.org/mikefarah/yq) ![Docker Pulls](https://img.shields.io/docker/pulls/mikefarah/yq.svg) ![Github Releases (by Release)](https://img.shields.io/github/downloads/mikefarah/yq/total.svg) @@ -82,6 +82,8 @@ docker run -it -v ${PWD}:/workdir mikefarah/yq sh Check out the [documentation](http://mikefarah.github.io/yq/) for more detailed and advanced usage. ``` +yq is a lightweight and portable command-line YAML processor. It aims to be the jq or sed of yaml files. + Usage: yq [flags] yq [command] @@ -91,9 +93,9 @@ Available Commands: help Help about any command merge yq m [--inplace/-i] [--doc/-d index] [--overwrite/-x] [--append/-a] sample.yaml sample2.yaml new yq n [--script/-s script_file] a.b.c newValue + prefix yq p [--inplace/-i] [--doc/-d index] sample.yaml a.b.c read yq r [--doc/-d index] sample.yaml a.b.c write yq w [--inplace/-i] [--script/-s script_file] [--doc/-d index] sample.yaml a.b.c newValue - prefix yq p [--inplace/-i] [--doc/-d index] sample.yaml a.b.c Flags: -h, --help help for yq @@ -110,8 +112,8 @@ Use "yq [command] --help" for more information about a command. 3. add unit tests 4. apply changes (use govendor with a preference to [gopkg](https://gopkg.in/) for package dependencies) 5. `make [local] build` -6. If required, update the user documentation +6. If required, update the user documentation - Update README.md and/or documentation under the mkdocs folder - `make [local] build-docs` - - browse to docs/index.html and check your changes + - browse to docs/index.html and check your changes 7. profit diff --git a/commands_test.go b/commands_test.go index e01fb700..d74fff56 100644 --- a/commands_test.go +++ b/commands_test.go @@ -24,7 +24,18 @@ func TestRootCmd(t *testing.T) { if !strings.Contains(result.Output, "Usage:") { t.Error("Expected usage message to be printed out, but the usage message was not found.") } +} +func TestRootCmd_Help(t *testing.T) { + cmd := getRootCommand() + result := runCmd(cmd, "--help") + if result.Error != nil { + t.Error(result.Error) + } + + if !strings.Contains(result.Output, "yq is a lightweight and portable command-line YAML processor. It aims to be the jq or sed of yaml files.") { + t.Error("Expected usage message to be printed out, but the usage message was not found.") + } } func TestRootCmd_VerboseLong(t *testing.T) { @@ -906,9 +917,9 @@ func TestDeleteSplatArrayYaml(t *testing.T) { content := `a: 2 b: hi: - - thing: item1 + - thing: item1 name: fred - - thing: item2 + - thing: item2 name: sam ` filename := writeTempYamlFile(content) diff --git a/docs/search/search_index.json b/docs/search/search_index.json index 1f03fe8d..47b7191a 100644 --- a/docs/search/search_index.json +++ b/docs/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"yq \u00b6 yq is a lightweight and portable command-line YAML processor The aim of the project is to be the jq or sed of yaml files. Install \u00b6 On MacOS: brew install yq On Ubuntu and other Linux distros supporting snap packages: snap install yq On Ubuntu 16.04 or higher from Debian package: sudo add-apt-repository ppa:rmescandon/yq sudo apt update sudo apt install yq -y or, Download latest binary or alternatively: go get gopkg.in/mikefarah/yq.v2 View on GitHub","title":"Install"},{"location":"#yq","text":"yq is a lightweight and portable command-line YAML processor The aim of the project is to be the jq or sed of yaml files.","title":"yq"},{"location":"#install","text":"On MacOS: brew install yq On Ubuntu and other Linux distros supporting snap packages: snap install yq On Ubuntu 16.04 or higher from Debian package: sudo add-apt-repository ppa:rmescandon/yq sudo apt update sudo apt install yq -y or, Download latest binary or alternatively: go get gopkg.in/mikefarah/yq.v2 View on GitHub","title":"Install"},{"location":"convert/","text":"Yaml to Json \u00b6 To convert output to json, use the --tojson (or -j) flag. This can only be used with the read command. Given a sample.yaml file of: b: c: 2 then yq r -j sample.yaml b.c will output {\"b\":{\"c\":2}} Json to Yaml \u00b6 To read in json, just pass in a json file instead of yaml, it will just work :) e.g given a json file {\"a\":\"Easy! as one two three\",\"b\":{\"c\":2,\"d\":[3,4]}} then yq r sample.json will output a: Easy! as one two three b: c: 2 d: - 3 - 4","title":"Convert"},{"location":"convert/#yaml-to-json","text":"To convert output to json, use the --tojson (or -j) flag. This can only be used with the read command. Given a sample.yaml file of: b: c: 2 then yq r -j sample.yaml b.c will output {\"b\":{\"c\":2}}","title":"Yaml to Json"},{"location":"convert/#json-to-yaml","text":"To read in json, just pass in a json file instead of yaml, it will just work :) e.g given a json file {\"a\":\"Easy! as one two three\",\"b\":{\"c\":2,\"d\":[3,4]}} then yq r sample.json will output a: Easy! as one two three b: c: 2 d: - 3 - 4","title":"Json to Yaml"},{"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. Currently this does not support creating multiple documents in a single yaml file. yq n Creating a simple yaml file \u00b6 yq n b.c cat will output: b: c: cat Creating using a create script \u00b6 Create scripts follow the same format as the update scripts. Given a script create_instructions.yaml of: b.c: 3 b.e[0].name: Howdy Partner then yq n -s create_instructions.yaml will output: b: c: 3 e: - name: Howdy Partner You can also pipe the instructions in: cat create_instructions.yaml | yq n -s - Keys with dots \u00b6 When specifying a key that has a dot use key lookup indicator. b: 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. Keys (and values) with leading dashes \u00b6 If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error). To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so: yq n -t -- --key --value Will result in ` --key: --value","title":"Create"},{"location":"create/#creating-a-simple-yaml-file","text":"yq n b.c cat will output: b: c: cat","title":"Creating a simple yaml file"},{"location":"create/#creating-using-a-create-script","text":"Create scripts follow the same format as the update scripts. Given a script create_instructions.yaml of: b.c: 3 b.e[0].name: Howdy Partner then yq n -s create_instructions.yaml will output: b: c: 3 e: - name: Howdy Partner You can also pipe the instructions in: cat create_instructions.yaml | yq n -s -","title":"Creating using a create script"},{"location":"create/#keys-with-dots","text":"When specifying a key that has a dot use key lookup indicator. b: 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/#keys-and-values-with-leading-dashes","text":"If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error). To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so: yq n -t -- --key --value Will result in ` --key: --value","title":"Keys (and values) with leading dashes"},{"location":"delete/","text":"yq d To Stdout \u00b6 Given a sample.yaml file of: b: c: 2 apples: green then yq d sample.yaml b.c will output: b: apples: green From STDIN \u00b6 cat sample.yaml | yq d - b.c Deleting array elements \u00b6 Given a sample.yaml file of: b: c: - 1 - 2 - 3 then yq d sample.yaml 'b.c[1]' will output: b: c: - 1 - 3 Deleting nodes in-place \u00b6 Given a sample.yaml file of: b: c: 2 apples: green then yq d -i sample.yaml b.c will update the sample.yaml file so that the 'c' node is deleted Multiple Documents - delete from single document \u00b6 Given a sample.yaml file of: something: else field: leaveMe --- b: c: 2 field: deleteMe then yq w -d1 sample.yaml field will output: something: else field: leaveMe --- b: c: 2 Multiple Documents - delete from all documents \u00b6 Given a sample.yaml file of: something: else field: deleteMe --- b: c: 2 field: deleteMeToo then yq w -d'*' sample.yaml field will output: something: else --- b: c: 2 Note that '*' is in quotes to avoid being interpreted by your shell. Keys with dots \u00b6 When specifying a key that has a dot use key lookup indicator. b: 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. Keys (and values) with leading dashes \u00b6 If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error). To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so: yq n -t -- --key --value Will result in ` --key: --value","title":"Delete"},{"location":"delete/#to-stdout","text":"Given a sample.yaml file of: b: c: 2 apples: green then yq d sample.yaml b.c will output: b: apples: green","title":"To Stdout"},{"location":"delete/#from-stdin","text":"cat sample.yaml | yq d - b.c","title":"From STDIN"},{"location":"delete/#deleting-array-elements","text":"Given a sample.yaml file of: b: c: - 1 - 2 - 3 then yq d sample.yaml 'b.c[1]' will output: b: c: - 1 - 3","title":"Deleting array elements"},{"location":"delete/#deleting-nodes-in-place","text":"Given a sample.yaml file of: b: c: 2 apples: green then yq d -i sample.yaml b.c will update the sample.yaml file so that the 'c' node is deleted","title":"Deleting nodes in-place"},{"location":"delete/#multiple-documents-delete-from-single-document","text":"Given a sample.yaml file of: something: else field: leaveMe --- b: c: 2 field: deleteMe then yq w -d1 sample.yaml field will output: something: else field: leaveMe --- b: c: 2","title":"Multiple Documents - delete from single document"},{"location":"delete/#multiple-documents-delete-from-all-documents","text":"Given a sample.yaml file of: something: else field: deleteMe --- b: c: 2 field: deleteMeToo then yq w -d'*' sample.yaml field will output: something: else --- b: c: 2 Note that '*' is in quotes to avoid being interpreted by your shell.","title":"Multiple Documents - delete from all documents"},{"location":"delete/#keys-with-dots","text":"When specifying a key that has a dot use key lookup indicator. b: 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":"delete/#keys-and-values-with-leading-dashes","text":"If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error). To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so: yq n -t -- --key --value Will result in ` --key: --value","title":"Keys (and values) with leading dashes"},{"location":"merge/","text":"Yaml files can be merged using the 'merge' command. Each additional file merged with the first file will set values for any key not existing already or where the key has no value. yq m ... To Stdout \u00b6 Given a data1.yaml file of: a: simple b: [1, 2] and data2.yaml file of: a: other c: test: 1 then yq m data1.yaml data2.yaml will output: a: simple b: [1, 2] c: test: 1 Updating files in-place \u00b6 Given a data1.yaml file of: a: simple b: [1, 2] and data2.yaml file of: a: other c: test: 1 then yq m -i data1.yaml data2.yaml will update the data1.yaml file so that the value of 'c' is 'test: 1'. Overwrite values \u00b6 Given a data1.yaml file of: a: simple b: [1, 2] and data2.yaml file of: a: other c: test: 1 then yq m -x data1.yaml data2.yaml will output: a: other b: [1, 2] c: test: 1 Overwrite values with arrays \u00b6 Given a data1.yaml file of: a: simple b: [1, 2] and data3.yaml file of: b: [3, 4] c: test: 2 other: true d: false then yq m -x data1.yaml data3.yaml will output: a: simple b: [3, 4] c: test: 2 other: true d: false Notice that 'b' does not result in the merging of the values within an array. Append values with arrays \u00b6 Given a data1.yaml file of: a: simple b: [1, 2] d: hi and data3.yaml file of: a: something b: [3, 4] c: test: 2 other: true then yq m -a data1.yaml data3.yaml will output: a: simple b: [1, 2, 3, 4] c: test: 2 other: true d: hi Note that the 'b' array has concatenated the values from the second data file. Also note that other map keys are not overridden (field a). Append cannot be used with overwrite, if both flags are given then append is ignored. Multiple Documents - merge into single document \u00b6 Currently yq only has multi-document support for the first document being merged into. The remaining yaml files will have their first document selected. Given a data1.yaml file of: something: else --- a: simple b: cat and data3.yaml file of: b: dog then yq m -x -d1 data1.yaml data3.yaml will output: something: else --- a: simple b: dog Multiple Documents - merge into all documents \u00b6 Currently yq only has multi-document support for the first document being merged into. The remaining yaml files will have their first document selected. Given a data1.yaml file of: something: else --- a: simple b: cat and data3.yaml file of: b: dog then yq m -x -d'*' data1.yaml data3.yaml will output: b: dog something: else --- a: simple b: dog","title":"Merge"},{"location":"merge/#to-stdout","text":"Given a data1.yaml file of: a: simple b: [1, 2] and data2.yaml file of: a: other c: test: 1 then yq m data1.yaml data2.yaml will output: a: simple b: [1, 2] c: test: 1","title":"To Stdout"},{"location":"merge/#updating-files-in-place","text":"Given a data1.yaml file of: a: simple b: [1, 2] and data2.yaml file of: a: other c: test: 1 then yq m -i data1.yaml data2.yaml will update the data1.yaml file so that the value of 'c' is 'test: 1'.","title":"Updating files in-place"},{"location":"merge/#overwrite-values","text":"Given a data1.yaml file of: a: simple b: [1, 2] and data2.yaml file of: a: other c: test: 1 then yq m -x data1.yaml data2.yaml will output: a: other b: [1, 2] c: test: 1","title":"Overwrite values"},{"location":"merge/#overwrite-values-with-arrays","text":"Given a data1.yaml file of: a: simple b: [1, 2] and data3.yaml file of: b: [3, 4] c: test: 2 other: true d: false then yq m -x data1.yaml data3.yaml will output: a: simple b: [3, 4] c: test: 2 other: true d: false Notice that 'b' does not result in the merging of the values within an array.","title":"Overwrite values with arrays"},{"location":"merge/#append-values-with-arrays","text":"Given a data1.yaml file of: a: simple b: [1, 2] d: hi and data3.yaml file of: a: something b: [3, 4] c: test: 2 other: true then yq m -a data1.yaml data3.yaml will output: a: simple b: [1, 2, 3, 4] c: test: 2 other: true d: hi Note that the 'b' array has concatenated the values from the second data file. Also note that other map keys are not overridden (field a). Append cannot be used with overwrite, if both flags are given then append is ignored.","title":"Append values with arrays"},{"location":"merge/#multiple-documents-merge-into-single-document","text":"Currently yq only has multi-document support for the first document being merged into. The remaining yaml files will have their first document selected. Given a data1.yaml file of: something: else --- a: simple b: cat and data3.yaml file of: b: dog then yq m -x -d1 data1.yaml data3.yaml will output: something: else --- a: simple b: dog","title":"Multiple Documents - merge into single document"},{"location":"merge/#multiple-documents-merge-into-all-documents","text":"Currently yq only has multi-document support for the first document being merged into. The remaining yaml files will have their first document selected. Given a data1.yaml file of: something: else --- a: simple b: cat and data3.yaml file of: b: dog then yq m -x -d'*' data1.yaml data3.yaml will output: b: dog something: else --- a: simple b: dog","title":"Multiple Documents - merge into all documents"},{"location":"prefix/","text":"Paths can be prefixed using the 'prefix' command. The complete yaml content will be nested inside the new prefix path. yq p To Stdout \u00b6 Given a data1.yaml file of: a: simple b: [1, 2] then yq p data1.yaml c will output: c: a: simple b: [1, 2] Arbitrary depth \u00b6 Given a data1.yaml file of: a: b: [1, 2] then yq p data1.yaml c.d will output: c: d: a: b: [1, 2] Updating files in-place \u00b6 Given a data1.yaml file of: a: simple b: [1, 2] then yq p -i data1.yaml c will update the data1.yaml file so that the path 'c' is prefixed to all other paths. Multiple Documents - prefix a single document \u00b6 Given a data1.yaml file of: something: else --- a: simple b: cat then yq p -d1 data1.yaml c will output: something: else --- c: a: simple b: cat Multiple Documents - prefix all documents \u00b6 Given a data1.yaml file of: something: else --- a: simple b: cat then yq p -d'*' data1.yaml c will output: c: something: else --- c: a: simple b: cat","title":"Prefix"},{"location":"prefix/#to-stdout","text":"Given a data1.yaml file of: a: simple b: [1, 2] then yq p data1.yaml c will output: c: a: simple b: [1, 2]","title":"To Stdout"},{"location":"prefix/#arbitrary-depth","text":"Given a data1.yaml file of: a: b: [1, 2] then yq p data1.yaml c.d will output: c: d: a: b: [1, 2]","title":"Arbitrary depth"},{"location":"prefix/#updating-files-in-place","text":"Given a data1.yaml file of: a: simple b: [1, 2] then yq p -i data1.yaml c will update the data1.yaml file so that the path 'c' is prefixed to all other paths.","title":"Updating files in-place"},{"location":"prefix/#multiple-documents-prefix-a-single-document","text":"Given a data1.yaml file of: something: else --- a: simple b: cat then yq p -d1 data1.yaml c will output: something: else --- c: a: simple b: cat","title":"Multiple Documents - prefix a single document"},{"location":"prefix/#multiple-documents-prefix-all-documents","text":"Given a data1.yaml file of: something: else --- a: simple b: cat then yq p -d'*' data1.yaml c will output: c: something: else --- c: a: simple b: cat","title":"Multiple Documents - prefix all documents"},{"location":"read/","text":"yq r This command can take a json file as input too, and will output yaml unless specified to export as json (-j) Basic \u00b6 Given a sample.yaml file of: b: c: 2 then yq r sample.yaml b.c will output the value of '2'. From Stdin \u00b6 Given a sample.yaml file of: cat sample.yaml | yq r - b.c will output the value of '2'. Splat \u00b6 Given a sample.yaml file of: --- bob: item1: cats: bananas item2: cats: apples then yq r sample.yaml bob.*.cats will output - bananas - apples Multiple Documents - specify a single document \u00b6 Given a sample.yaml file of: something: else --- b: c: 2 then yq r -d1 sample.yaml b.c will output the value of '2'. Multiple Documents - read all documents \u00b6 Reading all documents will return the result as an array. This can be converted to json using the '-j' flag if desired. Given a sample.yaml file of: name: Fred age: 22 --- name: Stella age: 23 --- name: Android age: 232 then yq r -d'*' sample.yaml name will output: - Fred - Stella - Android Arrays \u00b6 You can give an index to access a specific element: e.g.: given a sample file of b: e: - name: fred value: 3 - name: sam 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. Array Splat \u00b6 e.g.: given a sample file of b: e: - name: fred value: 3 - name: sam value: 4 then 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. Keys with dots \u00b6 When specifying a key that has a dot use key lookup indicator. b: 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. Keys (and values) with leading dashes \u00b6 If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error). To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so: yq n -t -- --key --value Will result in ` --key: --value","title":"Read"},{"location":"read/#basic","text":"Given a sample.yaml file of: b: c: 2 then yq r sample.yaml b.c will output the value of '2'.","title":"Basic"},{"location":"read/#from-stdin","text":"Given a sample.yaml file of: cat sample.yaml | yq r - b.c will output the value of '2'.","title":"From Stdin"},{"location":"read/#splat","text":"Given a sample.yaml file of: --- bob: item1: cats: bananas item2: cats: apples then yq r sample.yaml bob.*.cats will output - bananas - apples","title":"Splat"},{"location":"read/#multiple-documents-specify-a-single-document","text":"Given a sample.yaml file of: something: else --- b: c: 2 then yq r -d1 sample.yaml b.c will output the value of '2'.","title":"Multiple Documents - specify a single document"},{"location":"read/#multiple-documents-read-all-documents","text":"Reading all documents will return the result as an array. This can be converted to json using the '-j' flag if desired. Given a sample.yaml file of: name: Fred age: 22 --- name: Stella age: 23 --- name: Android age: 232 then yq r -d'*' sample.yaml name will output: - Fred - Stella - Android","title":"Multiple Documents - read all documents"},{"location":"read/#arrays","text":"You can give an index to access a specific element: e.g.: given a sample file of b: e: - name: fred value: 3 - name: sam 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: e: - name: fred value: 3 - name: sam value: 4 then 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.","title":"Array Splat"},{"location":"read/#keys-with-dots","text":"When specifying a key that has a dot use key lookup indicator. b: 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":"read/#keys-and-values-with-leading-dashes","text":"If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error). To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so: yq n -t -- --key --value Will result in ` --key: --value","title":"Keys (and values) with leading dashes"},{"location":"write/","text":"yq w To Stdout \u00b6 Given a sample.yaml file of: b: c: 2 then yq w sample.yaml b.c cat will output: b: c: cat From STDIN \u00b6 cat sample.yaml | yq w - b.c blah Adding new fields \u00b6 Any missing fields in the path will be created on the fly. Given a sample.yaml file of: b: c: 2 then yq w sample.yaml b.d[0] \"new thing\" will output: b: c: cat d: - new thing Appending value to an array field \u00b6 Given a sample.yaml file of: b: c: 2 d: - new thing - foo thing then yq w sample.yaml \"b.d[+]\" \"bar thing\" will output: b: c: cat d: - new thing - foo thing - bar thing Note that the path is in quotes to avoid the square brackets being interpreted by your shell. Multiple Documents - update a single document \u00b6 Given a sample.yaml file of: something: else --- b: c: 2 then yq w -d1 sample.yaml b.c 5 will output: something: else --- b: c: 5 Multiple Documents - update all documents \u00b6 Given a sample.yaml file of: something: else --- b: c: 2 then yq w -d'*' sample.yaml b.c 5 will output: something: else b: c: 5 --- b: c: 5 Note that '*' is in quotes to avoid being interpreted by your shell. Updating files in-place \u00b6 Given a sample.yaml file of: b: c: 2 then yq w -i sample.yaml b.c cat will update the sample.yaml file so that the value of 'c' is cat. Updating multiple values with a script \u00b6 Given a sample.yaml file of: b: c: 2 e: - name: Billy Bob and a script update_instructions.yaml of: b.c: 3 b.e[0].name: Howdy Partner then yq w -s update_instructions.yaml sample.yaml will output: b: c: 3 e: - name: Howdy Partner And, of course, you can pipe the instructions in using '-': cat update_instructions.yaml | yq w -s - sample.yaml Values starting with a hyphen (or dash) \u00b6 The flag terminator needs to be used to stop the app from attempting to parse the subsequent arguments as flags: yq w -- my.path -3 will output my: path: -3 Keys with dots \u00b6 When specifying a key that has a dot use key lookup indicator. b: 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. Keys (and values) with leading dashes \u00b6 If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error). To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so: yq n -t -- --key --value Will result in ` --key: --value","title":"Write/Update"},{"location":"write/#to-stdout","text":"Given a sample.yaml file of: b: c: 2 then yq w sample.yaml b.c cat will output: b: c: cat","title":"To Stdout"},{"location":"write/#from-stdin","text":"cat sample.yaml | yq w - b.c blah","title":"From STDIN"},{"location":"write/#adding-new-fields","text":"Any missing fields in the path will be created on the fly. Given a sample.yaml file of: b: c: 2 then yq w sample.yaml b.d[0] \"new thing\" will output: b: c: cat d: - new thing","title":"Adding new fields"},{"location":"write/#appending-value-to-an-array-field","text":"Given a sample.yaml file of: b: c: 2 d: - new thing - foo thing then yq w sample.yaml \"b.d[+]\" \"bar thing\" will output: b: c: cat d: - new thing - foo thing - 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"},{"location":"write/#multiple-documents-update-a-single-document","text":"Given a sample.yaml file of: something: else --- b: c: 2 then yq w -d1 sample.yaml b.c 5 will output: something: else --- b: c: 5","title":"Multiple Documents - update a single document"},{"location":"write/#multiple-documents-update-all-documents","text":"Given a sample.yaml file of: something: else --- b: c: 2 then yq w -d'*' sample.yaml b.c 5 will output: something: else b: c: 5 --- b: c: 5 Note that '*' is in quotes to avoid being interpreted by your shell.","title":"Multiple Documents - update all documents"},{"location":"write/#updating-files-in-place","text":"Given a sample.yaml file of: b: c: 2 then yq w -i sample.yaml b.c cat will update the sample.yaml file so that the value of 'c' is cat.","title":"Updating files in-place"},{"location":"write/#updating-multiple-values-with-a-script","text":"Given a sample.yaml file of: b: c: 2 e: - name: Billy Bob and a script update_instructions.yaml of: b.c: 3 b.e[0].name: Howdy Partner then yq w -s update_instructions.yaml sample.yaml will output: b: c: 3 e: - name: Howdy Partner And, of course, you can pipe the instructions in using '-': cat update_instructions.yaml | yq w -s - sample.yaml","title":"Updating multiple values with a script"},{"location":"write/#values-starting-with-a-hyphen-or-dash","text":"The flag terminator needs to be used to stop the app from attempting to parse the subsequent arguments as flags: yq w -- my.path -3 will output my: path: -3","title":"Values starting with a hyphen (or dash)"},{"location":"write/#keys-with-dots","text":"When specifying a key that has a dot use key lookup indicator. b: 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/#keys-and-values-with-leading-dashes","text":"If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error). To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so: yq n -t -- --key --value Will result in ` --key: --value","title":"Keys (and values) with leading dashes"},{"location":"snippets/niche/","text":"Keys with dots \u00b6 When specifying a key that has a dot use key lookup indicator. b: 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. Keys (and values) with leading dashes \u00b6 If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error). To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so: yq n -t -- --key --value Will result in --key: --value","title":"Niche"},{"location":"snippets/niche/#keys-with-dots","text":"When specifying a key that has a dot use key lookup indicator. b: 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":"snippets/niche/#keys-and-values-with-leading-dashes","text":"If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error). To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so: yq n -t -- --key --value Will result in --key: --value","title":"Keys (and values) with leading dashes"},{"location":"snippets/works_with_json/","text":"This command can take a json file as input too, and will output yaml unless specified to export as json (-j)","title":"Works with json"}]} \ No newline at end of file +{"config":{"lang":["en"],"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"yq yq is a lightweight and portable command-line YAML processor The aim of the project is to be the jq or sed of yaml files. Install On MacOS: brew install yq On Ubuntu and other Linux distros supporting snap packages: snap install yq On Ubuntu 16.04 or higher from Debian package: sudo add-apt-repository ppa:rmescandon/yq sudo apt update sudo apt install yq -y or, Download latest binary or alternatively: go get gopkg.in/mikefarah/yq.v2 View on GitHub","title":"Install"},{"location":"#yq","text":"yq is a lightweight and portable command-line YAML processor The aim of the project is to be the jq or sed of yaml files.","title":"yq"},{"location":"#install","text":"On MacOS: brew install yq On Ubuntu and other Linux distros supporting snap packages: snap install yq On Ubuntu 16.04 or higher from Debian package: sudo add-apt-repository ppa:rmescandon/yq sudo apt update sudo apt install yq -y or, Download latest binary or alternatively: go get gopkg.in/mikefarah/yq.v2 View on GitHub","title":"Install"},{"location":"convert/","text":"Yaml to Json To convert output to json, use the --tojson (or -j) flag. This can only be used with the read command. Given a sample.yaml file of: b: c: 2 then yq r -j sample.yaml b.c will output { b :{ c :2}} Json to Yaml To read in json, just pass in a json file instead of yaml, it will just work :) e.g given a json file { a : Easy! as one two three , b :{ c :2, d :[3,4]}} then yq r sample.json will output a: Easy! as one two three b: c: 2 d: - 3 - 4","title":"Convert"},{"location":"convert/#yaml-to-json","text":"To convert output to json, use the --tojson (or -j) flag. This can only be used with the read command. Given a sample.yaml file of: b: c: 2 then yq r -j sample.yaml b.c will output { b :{ c :2}}","title":"Yaml to Json"},{"location":"convert/#json-to-yaml","text":"To read in json, just pass in a json file instead of yaml, it will just work :) e.g given a json file { a : Easy! as one two three , b :{ c :2, d :[3,4]}} then yq r sample.json will output a: Easy! as one two three b: c: 2 d: - 3 - 4","title":"Json to Yaml"},{"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. Currently this does not support creating multiple documents in a single yaml file. yq n path new value Creating a simple yaml file yq n b.c cat will output: b: c: cat Creating using a create script Create scripts follow the same format as the update scripts. Given a script create_instructions.yaml of: b.c: 3 b.e[0].name: Howdy Partner then yq n -s create_instructions.yaml will output: b: c: 3 e: - name: Howdy Partner You can also pipe the instructions in: cat create_instructions.yaml | yq n -s - 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 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. Keys (and values) with leading dashes If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error). To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so: yq n -t -- --key --value Will result in ` --key: --value","title":"Create"},{"location":"create/#creating-a-simple-yaml-file","text":"yq n b.c cat will output: b: c: cat","title":"Creating a simple yaml file"},{"location":"create/#creating-using-a-create-script","text":"Create scripts follow the same format as the update scripts. Given a script create_instructions.yaml of: b.c: 3 b.e[0].name: Howdy Partner then yq n -s create_instructions.yaml will output: b: c: 3 e: - name: Howdy Partner You can also pipe the instructions in: cat create_instructions.yaml | yq n -s -","title":"Creating using a create script"},{"location":"create/#keys-with-dots","text":"When specifying a key that has a dot use key lookup indicator. b: 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/#keys-and-values-with-leading-dashes","text":"If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error). To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so: yq n -t -- --key --value Will result in ` --key: --value","title":"Keys (and values) with leading dashes"},{"location":"delete/","text":"yq d yaml_file path_to_delete To Stdout Given a sample.yaml file of: b: c: 2 apples: green then yq d sample.yaml b.c will output: b: apples: green From STDIN cat sample.yaml | yq d - b.c Deleting array elements Given a sample.yaml file of: b: c: - 1 - 2 - 3 then yq d sample.yaml 'b.c[1]' will output: b: c: - 1 - 3 Deleting nodes in-place Given a sample.yaml file of: b: c: 2 apples: green then yq d -i sample.yaml b.c will update the sample.yaml file so that the 'c' node is deleted Multiple Documents - delete from single document Given a sample.yaml file of: something: else field: leaveMe --- b: c: 2 field: deleteMe then yq w -d1 sample.yaml field will output: something: else field: leaveMe --- b: c: 2 Multiple Documents - delete from all documents Given a sample.yaml file of: something: else field: deleteMe --- b: c: 2 field: deleteMeToo then yq w -d'*' sample.yaml field will output: something: else --- b: c: 2 Note that '*' is in quotes to avoid 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 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. Keys (and values) with leading dashes If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error). To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so: yq n -t -- --key --value Will result in ` --key: --value","title":"Delete"},{"location":"delete/#to-stdout","text":"Given a sample.yaml file of: b: c: 2 apples: green then yq d sample.yaml b.c will output: b: apples: green","title":"To Stdout"},{"location":"delete/#from-stdin","text":"cat sample.yaml | yq d - b.c","title":"From STDIN"},{"location":"delete/#deleting-array-elements","text":"Given a sample.yaml file of: b: c: - 1 - 2 - 3 then yq d sample.yaml 'b.c[1]' will output: b: c: - 1 - 3","title":"Deleting array elements"},{"location":"delete/#deleting-nodes-in-place","text":"Given a sample.yaml file of: b: c: 2 apples: green then yq d -i sample.yaml b.c will update the sample.yaml file so that the 'c' node is deleted","title":"Deleting nodes in-place"},{"location":"delete/#multiple-documents-delete-from-single-document","text":"Given a sample.yaml file of: something: else field: leaveMe --- b: c: 2 field: deleteMe then yq w -d1 sample.yaml field will output: something: else field: leaveMe --- b: c: 2","title":"Multiple Documents - delete from single document"},{"location":"delete/#multiple-documents-delete-from-all-documents","text":"Given a sample.yaml file of: something: else field: deleteMe --- b: c: 2 field: deleteMeToo then yq w -d'*' sample.yaml field will output: something: else --- b: c: 2 Note that '*' is in quotes to avoid being interpreted by your shell.","title":"Multiple Documents - delete from all documents"},{"location":"delete/#keys-with-dots","text":"When specifying a key that has a dot use key lookup indicator. b: 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":"delete/#keys-and-values-with-leading-dashes","text":"If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error). To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so: yq n -t -- --key --value Will result in ` --key: --value","title":"Keys (and values) with leading dashes"},{"location":"merge/","text":"Yaml files can be merged using the 'merge' command. Each additional file merged with the first file will set values for any key not existing already or where the key has no value. yq m yaml_file path ... To Stdout Given a data1.yaml file of: a: simple b: [1, 2] and data2.yaml file of: a: other c: test: 1 then yq m data1.yaml data2.yaml will output: a: simple b: [1, 2] c: test: 1 Updating files in-place Given a data1.yaml file of: a: simple b: [1, 2] and data2.yaml file of: a: other c: test: 1 then yq m -i data1.yaml data2.yaml will update the data1.yaml file so that the value of 'c' is 'test: 1'. Overwrite values Given a data1.yaml file of: a: simple b: [1, 2] and data2.yaml file of: a: other c: test: 1 then yq m -x data1.yaml data2.yaml will output: a: other b: [1, 2] c: test: 1 Overwrite values with arrays Given a data1.yaml file of: a: simple b: [1, 2] and data3.yaml file of: b: [3, 4] c: test: 2 other: true d: false then yq m -x data1.yaml data3.yaml will output: a: simple b: [3, 4] c: test: 2 other: true d: false Notice that 'b' does not result in the merging of the values within an array. Append values with arrays Given a data1.yaml file of: a: simple b: [1, 2] d: hi and data3.yaml file of: a: something b: [3, 4] c: test: 2 other: true then yq m -a data1.yaml data3.yaml will output: a: simple b: [1, 2, 3, 4] c: test: 2 other: true d: hi Note that the 'b' array has concatenated the values from the second data file. Also note that other map keys are not overridden (field a). Append cannot be used with overwrite, if both flags are given then append is ignored. Multiple Documents - merge into single document Currently yq only has multi-document support for the first document being merged into. The remaining yaml files will have their first document selected. Given a data1.yaml file of: something: else --- a: simple b: cat and data3.yaml file of: b: dog then yq m -x -d1 data1.yaml data3.yaml will output: something: else --- a: simple b: dog Multiple Documents - merge into all documents Currently yq only has multi-document support for the first document being merged into. The remaining yaml files will have their first document selected. Given a data1.yaml file of: something: else --- a: simple b: cat and data3.yaml file of: b: dog then yq m -x -d'*' data1.yaml data3.yaml will output: b: dog something: else --- a: simple b: dog","title":"Merge"},{"location":"merge/#to-stdout","text":"Given a data1.yaml file of: a: simple b: [1, 2] and data2.yaml file of: a: other c: test: 1 then yq m data1.yaml data2.yaml will output: a: simple b: [1, 2] c: test: 1","title":"To Stdout"},{"location":"merge/#updating-files-in-place","text":"Given a data1.yaml file of: a: simple b: [1, 2] and data2.yaml file of: a: other c: test: 1 then yq m -i data1.yaml data2.yaml will update the data1.yaml file so that the value of 'c' is 'test: 1'.","title":"Updating files in-place"},{"location":"merge/#overwrite-values","text":"Given a data1.yaml file of: a: simple b: [1, 2] and data2.yaml file of: a: other c: test: 1 then yq m -x data1.yaml data2.yaml will output: a: other b: [1, 2] c: test: 1","title":"Overwrite values"},{"location":"merge/#overwrite-values-with-arrays","text":"Given a data1.yaml file of: a: simple b: [1, 2] and data3.yaml file of: b: [3, 4] c: test: 2 other: true d: false then yq m -x data1.yaml data3.yaml will output: a: simple b: [3, 4] c: test: 2 other: true d: false Notice that 'b' does not result in the merging of the values within an array.","title":"Overwrite values with arrays"},{"location":"merge/#append-values-with-arrays","text":"Given a data1.yaml file of: a: simple b: [1, 2] d: hi and data3.yaml file of: a: something b: [3, 4] c: test: 2 other: true then yq m -a data1.yaml data3.yaml will output: a: simple b: [1, 2, 3, 4] c: test: 2 other: true d: hi Note that the 'b' array has concatenated the values from the second data file. Also note that other map keys are not overridden (field a). Append cannot be used with overwrite, if both flags are given then append is ignored.","title":"Append values with arrays"},{"location":"merge/#multiple-documents-merge-into-single-document","text":"Currently yq only has multi-document support for the first document being merged into. The remaining yaml files will have their first document selected. Given a data1.yaml file of: something: else --- a: simple b: cat and data3.yaml file of: b: dog then yq m -x -d1 data1.yaml data3.yaml will output: something: else --- a: simple b: dog","title":"Multiple Documents - merge into single document"},{"location":"merge/#multiple-documents-merge-into-all-documents","text":"Currently yq only has multi-document support for the first document being merged into. The remaining yaml files will have their first document selected. Given a data1.yaml file of: something: else --- a: simple b: cat and data3.yaml file of: b: dog then yq m -x -d'*' data1.yaml data3.yaml will output: b: dog something: else --- a: simple b: dog","title":"Multiple Documents - merge into all documents"},{"location":"prefix/","text":"Paths can be prefixed using the 'prefix' command. The complete yaml content will be nested inside the new prefix path. yq p yaml_file path To Stdout Given a data1.yaml file of: a: simple b: [1, 2] then yq p data1.yaml c will output: c: a: simple b: [1, 2] Arbitrary depth Given a data1.yaml file of: a: b: [1, 2] then yq p data1.yaml c.d will output: c: d: a: b: [1, 2] Updating files in-place Given a data1.yaml file of: a: simple b: [1, 2] then yq p -i data1.yaml c will update the data1.yaml file so that the path 'c' is prefixed to all other paths. Multiple Documents - prefix a single document Given a data1.yaml file of: something: else --- a: simple b: cat then yq p -d1 data1.yaml c will output: something: else --- c: a: simple b: cat Multiple Documents - prefix all documents Given a data1.yaml file of: something: else --- a: simple b: cat then yq p -d'*' data1.yaml c will output: c: something: else --- c: a: simple b: cat","title":"Prefix"},{"location":"prefix/#to-stdout","text":"Given a data1.yaml file of: a: simple b: [1, 2] then yq p data1.yaml c will output: c: a: simple b: [1, 2]","title":"To Stdout"},{"location":"prefix/#arbitrary-depth","text":"Given a data1.yaml file of: a: b: [1, 2] then yq p data1.yaml c.d will output: c: d: a: b: [1, 2]","title":"Arbitrary depth"},{"location":"prefix/#updating-files-in-place","text":"Given a data1.yaml file of: a: simple b: [1, 2] then yq p -i data1.yaml c will update the data1.yaml file so that the path 'c' is prefixed to all other paths.","title":"Updating files in-place"},{"location":"prefix/#multiple-documents-prefix-a-single-document","text":"Given a data1.yaml file of: something: else --- a: simple b: cat then yq p -d1 data1.yaml c will output: something: else --- c: a: simple b: cat","title":"Multiple Documents - prefix a single document"},{"location":"prefix/#multiple-documents-prefix-all-documents","text":"Given a data1.yaml file of: something: else --- a: simple b: cat then yq p -d'*' data1.yaml c will output: c: something: else --- c: a: simple b: cat","title":"Multiple Documents - prefix all documents"},{"location":"read/","text":"yq r yaml_file|json_file path This command can take a json file as input too, and will output yaml unless specified to export as json (-j) Basic Given a sample.yaml file of: b: c: 2 then yq r sample.yaml b.c will output the value of '2'. From Stdin Given a sample.yaml file of: cat sample.yaml | yq r - b.c will output the value of '2'. Splat Given a sample.yaml file of: --- bob: item1: cats: bananas item2: cats: apples then yq r sample.yaml bob.*.cats will output - bananas - apples Multiple Documents - specify a single document Given a sample.yaml file of: something: else --- b: c: 2 then yq r -d1 sample.yaml b.c will output the value of '2'. Multiple Documents - read all documents Reading all documents will return the result as an array. This can be converted to json using the '-j' flag if desired. Given a sample.yaml file of: name: Fred age: 22 --- name: Stella age: 23 --- name: Android age: 232 then yq r -d'*' sample.yaml name will output: - Fred - Stella - Android Arrays You can give an index to access a specific element: e.g.: given a sample file of b: e: - name: fred value: 3 - name: sam 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. Array Splat e.g.: given a sample file of b: e: - name: fred value: 3 - name: sam value: 4 then 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. 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 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. Keys (and values) with leading dashes If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error). To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so: yq n -t -- --key --value Will result in ` --key: --value","title":"Read"},{"location":"read/#basic","text":"Given a sample.yaml file of: b: c: 2 then yq r sample.yaml b.c will output the value of '2'.","title":"Basic"},{"location":"read/#from-stdin","text":"Given a sample.yaml file of: cat sample.yaml | yq r - b.c will output the value of '2'.","title":"From Stdin"},{"location":"read/#splat","text":"Given a sample.yaml file of: --- bob: item1: cats: bananas item2: cats: apples then yq r sample.yaml bob.*.cats will output - bananas - apples","title":"Splat"},{"location":"read/#multiple-documents-specify-a-single-document","text":"Given a sample.yaml file of: something: else --- b: c: 2 then yq r -d1 sample.yaml b.c will output the value of '2'.","title":"Multiple Documents - specify a single document"},{"location":"read/#multiple-documents-read-all-documents","text":"Reading all documents will return the result as an array. This can be converted to json using the '-j' flag if desired. Given a sample.yaml file of: name: Fred age: 22 --- name: Stella age: 23 --- name: Android age: 232 then yq r -d'*' sample.yaml name will output: - Fred - Stella - Android","title":"Multiple Documents - read all documents"},{"location":"read/#arrays","text":"You can give an index to access a specific element: e.g.: given a sample file of b: e: - name: fred value: 3 - name: sam 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: e: - name: fred value: 3 - name: sam value: 4 then 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.","title":"Array Splat"},{"location":"read/#keys-with-dots","text":"When specifying a key that has a dot use key lookup indicator. b: 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":"read/#keys-and-values-with-leading-dashes","text":"If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error). To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so: yq n -t -- --key --value Will result in ` --key: --value","title":"Keys (and values) with leading dashes"},{"location":"write/","text":"yq w yaml_file path new value To Stdout Given a sample.yaml file of: b: c: 2 then yq w sample.yaml b.c cat will output: b: c: cat From STDIN cat sample.yaml | yq w - b.c blah Adding new fields Any missing fields in the path will be created on the fly. Given a sample.yaml file of: b: c: 2 then yq w sample.yaml b.d[0] new thing will output: b: c: cat d: - new thing Appending value to an array field Given a sample.yaml file of: b: c: 2 d: - new thing - foo thing then yq w sample.yaml b.d[+] bar thing will output: b: c: cat d: - new thing - foo thing - bar thing Note that the path is in quotes to avoid the square brackets being interpreted by your shell. Multiple Documents - update a single document Given a sample.yaml file of: something: else --- b: c: 2 then yq w -d1 sample.yaml b.c 5 will output: something: else --- b: c: 5 Multiple Documents - update all documents Given a sample.yaml file of: something: else --- b: c: 2 then yq w -d'*' sample.yaml b.c 5 will output: something: else b: c: 5 --- b: c: 5 Note that '*' is in quotes to avoid being interpreted by your shell. Updating files in-place Given a sample.yaml file of: b: c: 2 then yq w -i sample.yaml b.c cat will update the sample.yaml file so that the value of 'c' is cat. Updating multiple values with a script Given a sample.yaml file of: b: c: 2 e: - name: Billy Bob and a script update_instructions.yaml of: b.c: 3 b.e[0].name: Howdy Partner then yq w -s update_instructions.yaml sample.yaml will output: b: c: 3 e: - name: Howdy Partner And, of course, you can pipe the instructions in using '-': cat update_instructions.yaml | yq w -s - sample.yaml Values starting with a hyphen (or dash) The flag terminator needs to be used to stop the app from attempting to parse the subsequent arguments as flags: yq w -- my.path -3 will output my: path: -3 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 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. Keys (and values) with leading dashes If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error). To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so: yq n -t -- --key --value Will result in ` --key: --value","title":"Write/Update"},{"location":"write/#to-stdout","text":"Given a sample.yaml file of: b: c: 2 then yq w sample.yaml b.c cat will output: b: c: cat","title":"To Stdout"},{"location":"write/#from-stdin","text":"cat sample.yaml | yq w - b.c blah","title":"From STDIN"},{"location":"write/#adding-new-fields","text":"Any missing fields in the path will be created on the fly. Given a sample.yaml file of: b: c: 2 then yq w sample.yaml b.d[0] new thing will output: b: c: cat d: - new thing","title":"Adding new fields"},{"location":"write/#appending-value-to-an-array-field","text":"Given a sample.yaml file of: b: c: 2 d: - new thing - foo thing then yq w sample.yaml b.d[+] bar thing will output: b: c: cat d: - new thing - foo thing - 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"},{"location":"write/#multiple-documents-update-a-single-document","text":"Given a sample.yaml file of: something: else --- b: c: 2 then yq w -d1 sample.yaml b.c 5 will output: something: else --- b: c: 5","title":"Multiple Documents - update a single document"},{"location":"write/#multiple-documents-update-all-documents","text":"Given a sample.yaml file of: something: else --- b: c: 2 then yq w -d'*' sample.yaml b.c 5 will output: something: else b: c: 5 --- b: c: 5 Note that '*' is in quotes to avoid being interpreted by your shell.","title":"Multiple Documents - update all documents"},{"location":"write/#updating-files-in-place","text":"Given a sample.yaml file of: b: c: 2 then yq w -i sample.yaml b.c cat will update the sample.yaml file so that the value of 'c' is cat.","title":"Updating files in-place"},{"location":"write/#updating-multiple-values-with-a-script","text":"Given a sample.yaml file of: b: c: 2 e: - name: Billy Bob and a script update_instructions.yaml of: b.c: 3 b.e[0].name: Howdy Partner then yq w -s update_instructions.yaml sample.yaml will output: b: c: 3 e: - name: Howdy Partner And, of course, you can pipe the instructions in using '-': cat update_instructions.yaml | yq w -s - sample.yaml","title":"Updating multiple values with a script"},{"location":"write/#values-starting-with-a-hyphen-or-dash","text":"The flag terminator needs to be used to stop the app from attempting to parse the subsequent arguments as flags: yq w -- my.path -3 will output my: path: -3","title":"Values starting with a hyphen (or dash)"},{"location":"write/#keys-with-dots","text":"When specifying a key that has a dot use key lookup indicator. b: 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/#keys-and-values-with-leading-dashes","text":"If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error). To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so: yq n -t -- --key --value Will result in ` --key: --value","title":"Keys (and values) with leading dashes"},{"location":"snippets/niche/","text":"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 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. Keys (and values) with leading dashes If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error). To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so: yq n -t -- --key --value Will result in --key: --value","title":"Niche"},{"location":"snippets/niche/#keys-with-dots","text":"When specifying a key that has a dot use key lookup indicator. b: 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":"snippets/niche/#keys-and-values-with-leading-dashes","text":"If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error). To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so: yq n -t -- --key --value Will result in --key: --value","title":"Keys (and values) with leading dashes"},{"location":"snippets/works_with_json/","text":"This command can take a json file as input too, and will output yaml unless specified to export as json (-j)","title":"Works with json"}]} \ No newline at end of file diff --git a/docs/sitemap.xml b/docs/sitemap.xml index 921c0cd8..52d1935b 100644 --- a/docs/sitemap.xml +++ b/docs/sitemap.xml @@ -2,42 +2,42 @@ None - 2019-04-29 + 2019-05-14 daily None - 2019-04-29 + 2019-05-14 daily None - 2019-04-29 + 2019-05-14 daily None - 2019-04-29 + 2019-05-14 daily None - 2019-04-29 + 2019-05-14 daily None - 2019-04-29 + 2019-05-14 daily None - 2019-04-29 + 2019-05-14 daily None - 2019-04-29 + 2019-05-14 daily \ No newline at end of file diff --git a/docs/sitemap.xml.gz b/docs/sitemap.xml.gz index 890f0563b2088e1ab33b428b0794619a50b76471..c15bfb479ed8e64079f7a7755052592f559127b3 100644 GIT binary patch literal 201 zcmV;)05<<0iwFo5`r2Fq|8r?{Wo=<_E_iKh0PT}O4#FT1MfW`gVPBv|6E&3XT)NT& z5Q;4ch037S+e>XVdWX(t{`~oww;EnOI*aZ)fbp)x1z{Lzr+jT(Q{waKkZ*A%GJXpd zbVMoapu}yA{hrcc7zmiCJJ|#Ap`oDKGyt7V%E%6j45bCR;0j!Uf53N3U(8>g_pl1}0{{SR C_g!fK diff --git a/yq.go b/yq.go index e28c7ead..f005a83e 100644 --- a/yq.go +++ b/yq.go @@ -40,7 +40,9 @@ func main() { func newCommandCLI() *cobra.Command { yaml.DefaultMapType = reflect.TypeOf(yaml.MapSlice{}) var rootCmd = &cobra.Command{ - Use: "yq", + Use: "yq", + Short: "yq is a lightweight and portable command-line YAML processor.", + Long: `yq is a lightweight and portable command-line YAML processor. It aims to be the jq or sed of yaml files.`, RunE: func(cmd *cobra.Command, args []string) error { if version { cmd.Print(GetVersionDisplay())