yq/README.md

128 lines
4.0 KiB
Markdown
Raw Normal View History

2019-05-14 17:28:06 +00:00
# yq
2018-07-31 09:04:34 +00:00
2020-01-14 22:01:08 +00:00
[![Build Status](https://api.travis-ci.com/mikefarah/yq.svg?branch=master)](https://travis-ci.com/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) ![Go Report](https://goreportcard.com/badge/github.com/mikefarah/yq)
2018-07-10 11:46:36 +00:00
2017-12-17 22:11:08 +00:00
a lightweight and portable command-line YAML processor
2015-09-27 03:29:20 +00:00
2015-10-13 10:31:02 +00:00
The aim of the project is to be the [jq](https://github.com/stedolan/jq) or sed of yaml files.
2015-09-27 03:29:20 +00:00
2015-11-20 10:42:45 +00:00
## Install
### On MacOS:
2017-12-24 19:30:49 +00:00
```
brew install yq
```
### On Ubuntu and other Linux distros supporting `snap` packages:
```
snap install yq
```
#### Snap notes
`yq` installs with with [_strict confinement_](https://docs.snapcraft.io/snap-confinement/6233) 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](https://linux.die.net/man/1/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](https://github.com/mikefarah/yq/releases/latest) or alternatively:
2015-11-20 10:42:45 +00:00
```
2020-01-13 05:58:11 +00:00
GO111MODULE=on go get github.com/mikefarah/yq/v3
2015-11-20 10:42:45 +00:00
```
## Run with Docker
Oneshot use:
```bash
docker run --rm -v ${PWD}:/workdir mikefarah/yq yq [flags] <command> FILE...
```
Run commands interactively:
```bash
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:
```bash
yq() {
docker run --rm -i -v ${PWD}:/workdir mikefarah/yq yq $@
}
```
2015-10-13 10:31:02 +00:00
## 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
2017-04-12 11:17:54 +00:00
- 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
2018-11-18 17:40:51 +00:00
- Prefix a path to a yaml file
2015-10-13 10:31:02 +00:00
- Convert from json to yaml
- Convert from yaml to json
2017-04-12 11:30:29 +00:00
- Pipe data in by using '-'
- Merge multiple yaml files where each additional file sets values for missing or null value keys.
2018-07-07 05:27:15 +00:00
- Merge multiple yaml files and override previous values.
- Merge multiple yaml files and append array values.
2018-06-20 03:42:00 +00:00
- Supports multiple documents in a single yaml file
2015-09-29 00:20:31 +00:00
2017-12-17 22:11:08 +00:00
## [Usage](http://mikefarah.github.io/yq/)
2017-04-13 05:44:31 +00:00
2017-12-17 22:11:08 +00:00
Check out the [documentation](http://mikefarah.github.io/yq/) for more detailed and advanced usage.
2017-04-13 05:44:31 +00:00
2015-09-27 03:29:20 +00:00
```
2019-05-14 17:28:06 +00:00
yq is a lightweight and portable command-line YAML processor. It aims to be the jq or sed of yaml files.
2017-04-14 02:40:03 +00:00
Usage:
2017-12-17 22:11:08 +00:00
yq [flags]
yq [command]
2015-09-27 03:40:09 +00:00
2017-04-14 02:40:03 +00:00
Available Commands:
delete yq d [--inplace/-i] [--doc/-d index] sample.yaml a.b.c
help Help about any command
2018-07-07 05:27:15 +00:00
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
2019-05-14 17:28:06 +00:00
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
2015-10-05 03:41:01 +00:00
2017-04-14 02:40:03 +00:00
Flags:
2017-12-17 22:11:08 +00:00
-h, --help help for yq
-t, --trim trim yaml output (default true)
-v, --verbose verbose mode
-V, --version Print version information and quit
2015-10-05 23:01:33 +00:00
2017-12-17 22:11:08 +00:00
Use "yq [command] --help" for more information about a command.
2015-09-29 06:29:32 +00:00
```
## Contribute
2018-08-06 06:24:06 +00:00
1. `scripts/devtools.sh`
2. `make [local] vendor`
3. add unit tests
4. apply changes to go.mod
2018-08-06 06:24:06 +00:00
5. `make [local] build`
2019-05-14 17:28:06 +00:00
6. If required, update the user documentation
2018-06-12 00:16:54 +00:00
- Update README.md and/or documentation under the mkdocs folder
- `make [local] build-docs`
2019-05-14 17:28:06 +00:00
- browse to docs/index.html and check your changes
2018-08-06 06:24:06 +00:00
7. profit