From 720cc8f798c25ae65446aa8095f97e964c2f5212 Mon Sep 17 00:00:00 2001 From: Mike Farah Date: Thu, 30 Jan 2020 09:58:21 +1100 Subject: [PATCH] Update cli docs --- README.md | 44 +++++++++++++++++----------------------- cmd/delete.go | 2 +- cmd/read.go | 2 +- cmd/version.go | 4 ++-- cmd/write.go | 2 +- release_instructions.txt | 1 - scripts/devtools.sh | 2 +- snap/snapcraft.yaml | 2 +- 8 files changed, 26 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index a5cef938..e065ab95 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,9 @@ a lightweight and portable command-line YAML processor The aim of the project is to be the [jq](https://github.com/stedolan/jq) or sed of yaml files. +## New version! +V3 is officially out - if you've been using v2 and want/need to upgrade, checkout the [upgrade guide](https://mikefarah.gitbook.io/yq/upgrading-from-v2). + ## Install ### On MacOS: ``` @@ -70,44 +73,39 @@ yq() { ## Features - Written in portable go, so you can download a lovely dependency free binary -- Deep read a yaml file with a given path -- Update a yaml file given a path -- Update a yaml file given a script file +- [Deep read a yaml file with a given path expression](https://mikefarah.gitbook.io/yq/commands/read#basic) +- [List matching paths of a given path expression](https://mikefarah.gitbook.io/yq/commands/read#path-only) +- Update a yaml file given a [path expression](https://mikefarah.gitbook.io/yq/commands/write-update#basic) or [script file](https://mikefarah.gitbook.io/yq/commands/write-update#basic) - Update creates any missing entries in the path on the fly -- Create a yaml file given a deep path and value -- Create a yaml file given a script file -- Prefix a path to a yaml file -- Convert from json to yaml -- Convert from yaml to json -- Pipe data in by using '-' -- Merge multiple yaml files where each additional file sets values for missing or null value keys. -- Merge multiple yaml files and override previous values. -- Merge multiple yaml files and append array values. -- Supports multiple documents in a single yaml file +- Keeps yaml formatting and comments when updating +- Create a yaml file given a [deep path and value](https://mikefarah.gitbook.io/yq/commands/create#creating-a-simple-yaml-file) or a [script file](https://mikefarah.gitbook.io/yq/commands/create#creating-using-a-create-script) +- [Prefix a path to a yaml file](https://mikefarah.gitbook.io/yq/commands/prefix) +- [Convert to/from json to yaml](https://mikefarah.gitbook.io/yq/usage/convert) +- [Pipe data in by using '-'](https://mikefarah.gitbook.io/yq/commands/read#from-stdin) +- [Merge](https://mikefarah.gitbook.io/yq/commands/merge) multiple yaml files with various options for [overriding](https://mikefarah.gitbook.io/yq/commands/merge#overwrite-values) and [appending](https://mikefarah.gitbook.io/yq/commands/merge#append-values-with-arrays) +- Supports multiple documents in a single yaml file for [reading](https://mikefarah.gitbook.io/yq/commands/read#multiple-documents), [writing](https://mikefarah.gitbook.io/yq/commands/write-update#multiple-documents) and [merging](https://mikefarah.gitbook.io/yq/commands/merge#multiple-documents) -## [Usage](http://mikefarah.github.io/yq/) +## [Usage](https://mikefarah.gitbook.io/yq/) -Check out the [documentation](http://mikefarah.github.io/yq/) for more detailed and advanced usage. +Check out the [documentation](https://mikefarah.gitbook.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] Available Commands: - delete yq d [--inplace/-i] [--doc/-d index] sample.yaml a.b.c + delete yq d [--inplace/-i] [--doc/-d index] sample.yaml 'b.e(name==fred).value' 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 + read yq r [--printMode/-p pv] sample.yaml 'b.e(name==fr*).value' + write yq w [--inplace/-i] [--script/-s script_file] [--doc/-d index] sample.yaml 'b.e(name==fr*).value' newValue Flags: -h, --help help for yq - -t, --trim trim yaml output (default true) + -j, --tojson output as json -v, --verbose verbose mode -V, --version Print version information and quit @@ -120,8 +118,4 @@ Use "yq [command] --help" for more information about a command. 3. add unit tests 4. apply changes to go.mod 5. `make [local] build` -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 7. profit diff --git a/cmd/delete.go b/cmd/delete.go index 35ac8808..5d857751 100644 --- a/cmd/delete.go +++ b/cmd/delete.go @@ -10,7 +10,7 @@ func createDeleteCmd() *cobra.Command { var cmdDelete = &cobra.Command{ Use: "delete [yaml_file] [path_expression]", Aliases: []string{"d"}, - Short: "yq d [--inplace/-i] [--doc/-d index] sample.yaml a.b.c", + Short: "yq d [--inplace/-i] [--doc/-d index] sample.yaml 'b.e(name==fred).value'", Example: ` yq delete things.yaml 'a.b.c' yq delete things.yaml 'a.*.c' diff --git a/cmd/read.go b/cmd/read.go index a669a080..d9d3bd23 100644 --- a/cmd/read.go +++ b/cmd/read.go @@ -9,7 +9,7 @@ func createReadCmd() *cobra.Command { var cmdRead = &cobra.Command{ Use: "read [yaml_file] [path_expression]", Aliases: []string{"r"}, - Short: "yq r [--doc/-d index] sample.yaml 'a.b.c'", + Short: "yq r [--printMode/-p pv] sample.yaml 'b.e(name==fr*).value'", Example: ` yq read things.yaml 'a.b.c' yq r - 'a.b.c' # reads from stdin diff --git a/cmd/version.go b/cmd/version.go index 11a00675..e052b8e1 100644 --- a/cmd/version.go +++ b/cmd/version.go @@ -11,12 +11,12 @@ var ( GitDescribe string // Version is main version number that is being run at the moment. - Version = "3.0.0" + Version = "3.0.1" // VersionPrerelease is a pre-release marker for the version. If this is "" (empty string) // then it means that it is a final release. Otherwise, this is a pre-release // such as "dev" (in development), "beta", "rc1", etc. - VersionPrerelease = "beta" + VersionPrerelease = "" ) // ProductName is the name of the product diff --git a/cmd/write.go b/cmd/write.go index 04422f4b..0528d4fd 100644 --- a/cmd/write.go +++ b/cmd/write.go @@ -8,7 +8,7 @@ func createWriteCmd() *cobra.Command { var cmdWrite = &cobra.Command{ Use: "write [yaml_file] [path_expression] [value]", Aliases: []string{"w"}, - Short: "yq w [--inplace/-i] [--script/-s script_file] [--doc/-d index] sample.yaml a.b.c newValue", + Short: "yq w [--inplace/-i] [--script/-s script_file] [--doc/-d index] sample.yaml 'b.e(name==fr*).value' newValue", Example: ` yq write things.yaml 'a.b.c' true yq write things.yaml 'a.*.c' true diff --git a/release_instructions.txt b/release_instructions.txt index 07b005f7..bc950a26 100644 --- a/release_instructions.txt +++ b/release_instructions.txt @@ -2,7 +2,6 @@ - increment version in snapcraft.yaml - commit - tag git with same version number - - be sure to also tag with 'v' for gopkg.in - make sure local build passes - push tag to git - git push --tags diff --git a/scripts/devtools.sh b/scripts/devtools.sh index 3113b042..cbd12f36 100755 --- a/scripts/devtools.sh +++ b/scripts/devtools.sh @@ -1,4 +1,4 @@ #!/bin/sh set -e -wget -O - -q https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s v1.21.0 +wget -O- -nv https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s v1.23.1 go get golang.org/x/tools/cmd/goimports \ No newline at end of file diff --git a/snap/snapcraft.yaml b/snap/snapcraft.yaml index 1f96b906..f756dd77 100644 --- a/snap/snapcraft.yaml +++ b/snap/snapcraft.yaml @@ -1,5 +1,5 @@ name: yq -version: '3.0.0-beta' +version: '3.0.1' summary: A lightweight and portable command-line YAML processor description: | The aim of the project is to be the jq or sed of yaml files.