yq is a portable command-line YAML, JSON, XML, CSV, TOML and properties processor
Go to file
2020-01-11 11:44:02 +11:00
debian Fix Debian 'Architecture' 2019-03-21 12:39:47 +11:00
docs Updated docs re creating a new array 2019-05-16 14:57:34 +10:00
examples Improved handling of numeric keys 2019-05-16 10:03:54 +10:00
mkdocs Updated docs re creating a new array 2019-05-16 14:57:34 +10:00
pkg update imports for v2 module path 2019-12-06 13:58:56 +11:00
scripts test coverage and linting 2019-12-06 13:58:56 +11:00
snap Bumbed snapcraft version 2019-11-01 12:40:35 +11:00
test Move implementation files to yqlib and test packages to allow for imports: 2019-12-06 13:58:56 +11:00
.dockerignore Added formatter, fixed docker build 2019-10-31 08:21:19 +11:00
.gitignore Ignore vendor folder 2019-11-06 11:45:31 +11:00
.travis.yml update ci to use go 1.13, switch to golangci-lint 2019-10-31 08:21:19 +11:00
commands_test.go update imports for v2 module path 2019-12-06 13:58:56 +11:00
Dockerfile update ci to use go 1.13, switch to golangci-lint 2019-10-31 08:21:19 +11:00
Dockerfile.dev update ci to use go 1.13, switch to golangci-lint 2019-10-31 08:21:19 +11:00
go.mod attempt to fix go get 2019-12-02 10:37:06 +11:00
go.sum Added formatter, fixed docker build 2019-10-31 08:21:19 +11:00
LICENSE Added License (MIT) 2017-02-10 16:00:25 +11:00
Makefile update ci to use go 1.13, switch to golangci-lint 2019-10-31 08:21:19 +11:00
Makefile.variables Rename to yq 2017-12-18 15:29:41 +11:00
mkdocs.yml Update documentation 2018-11-20 08:53:25 +11:00
README.md Added note about v3 2020-01-11 11:44:02 +11:00
release_instructions.txt Updating release instructions 2019-11-13 12:26:33 +11:00
test.yml Version bump 2018-10-25 16:05:43 +11:00
version_test.go Incrementing version 2018-06-20 14:29:10 +10:00
version.go Incremented version 2019-11-01 10:47:38 +11:00
yq_test.go update imports for v2 module path 2019-12-06 13:58:56 +11:00
yq.go Log out original error if removing temporary file failed 2019-12-23 12:09:38 +11:00

yq

Build Status Docker Pulls Github Releases (by Release) Go Report

a lightweight and portable command-line YAML processor

The aim of the project is to be the jq or sed of yaml files.

Major upgrade - V3 beta is out!

This addresses a number of features requests and issues that have been raised :)

Currently only available only available as a binary release here or via docker mikefarah/yq:3.0.0-beta!

It does have a few breaking changes listed on the release page

Looking forward to feedback - once this is out of beta it will be added to the remaining package managers, and be the default version downloaded (and merged into master).

V2 will no longer have any new features added, and will be moved to a branch (v2). It will have limited maintenance for bugs for a few months.

Install

On MacOS:

brew install yq

On Ubuntu and other Linux distros supporting snap packages:

snap install yq

Snap notes

yq installs with with strict confinement in snap, this means it doesn't have direct access to root files. To read root files you can:

sudo cat /etc/myfile | yq -r - somecommand

And to write to a root file you can either use sponge:

sudo cat /etc/myfile | yq -r - somecommand | sudo sponge /etc/myfile

or write to a temporary file:

sudo cat /etc/myfile | yq -r - somecommand | sudo tee /etc/myfile.tmp
sudo mv /etc/myfile.tmp /etc/myfile
rm /etc/myfile.tmp

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:

GO111MODULE=on go get github.com/mikefarah/yq/v2

Run with Docker

Oneshot use:

docker run --rm -v ${PWD}:/workdir mikefarah/yq yq [flags] <command> FILE...

Run commands interactively:

docker run --rm -it -v ${PWD}:/workdir mikefarah/yq sh

It can be useful to have a bash function to avoid typing the whole docker command:

yq() {
  docker run --rm -i -v ${PWD}:/workdir mikefarah/yq 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
  • 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

Usage

Check out the documentation 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
  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

Flags:
  -h, --help      help for yq
  -t, --trim      trim yaml output (default true)
  -v, --verbose   verbose mode
  -V, --version   Print version information and quit

Use "yq [command] --help" for more information about a command.

Contribute

Note: v3 is currently in progress - for the moment I won't be accepting new feature PRs until v3 is ready :)

  1. scripts/devtools.sh
  2. make [local] vendor
  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