mirror of
https://github.com/mikefarah/yq.git
synced 2025-01-14 04:25:36 +00:00
Updating README
This commit is contained in:
Mike Farah
parent
a41131816a
commit
8c4ae979a2
208
README.md
208
README.md
@ -1,181 +1,51 @@
|
||||
---
|
||||
description: yq is a lightweight and portable command-line YAML processor
|
||||
---
|
||||
|
||||
# yq
|
||||
|
||||
`yq` is a lightweight and portable command-line YAML processor. `yq` uses [jq](https://github.com/stedolan/jq) like syntax but works with yaml files as well as json. It doesn't yet support everything `jq` does - but it does support the most common operations and functions, and more is being added continuously.
|
||||
a lightweight and portable command-line YAML processor. `yq` uses [jq](https://github.com/stedolan/jq) like syntax but works with yaml files as well as json. It doesn't yet support everything `jq` does - but it does support the most common operations and functions, and more is being added continuously.
|
||||
|
||||
`yq` is written in go - so you can download a dependency free binary for your platform and you are good to go! If you prefer there are a variety of package managers that can be used as well as docker, all listed below.
|
||||
yq is written in go - so you can download a dependency free binary for your platform and you are good to go! If you prefer there are a variety of package managers that can be used as well as docker, all listed below.
|
||||
|
||||
## v3 users:
|
||||
|
||||
Version 4 of `yq` is a major upgrade that now fully supports complex expressions for powerful filtering, slicing and dicing yaml documents. This new version uses syntax very similar to `jq` and works very similarly, so if you've used `jq` before this should be a low learning curve - however it is _quite_ different from previous versions of `yq`. Take a look at the [upgrade guide](upgrading-from-v3.md) for help.
|
||||
|
||||
Support for v3 will cease August 2021, until then, critical bug and security fixes will still get applied if required.
|
||||
|
||||
## How it works
|
||||
|
||||
`yq` works by running`yaml` nodes against a filter expression. The filter expression is made of of operators that pipe into each other. yaml nodes are piped through operators, operators may either return a different set of nodes (e.g. children) or modify the nodes (e.g. update values). See the [operator documentation](https://mikefarah.gitbook.io/yq/operators) for more details and examples.
|
||||
## Quick Usage Guide
|
||||
|
||||
Read a value:
|
||||
```bash
|
||||
yq e '.a.b[0].c' file.yaml
|
||||
```
|
||||
yq eval 'select(.a == "frog") | .b.c = "dragon"' file.yaml
|
||||
|
||||
Pipe from STDIN:
|
||||
```bash
|
||||
cat file.yaml | yq e '.a.b[0].c' -
|
||||
```
|
||||
|
||||
Update a yaml file, inplace
|
||||
```bash
|
||||
yq e -i '.a.b[0].c = "cool"' file.yaml
|
||||
```
|
||||
|
||||
Update using environment variables
|
||||
```bash
|
||||
NAME=mike yq e -i '.a.b[0].c = strenv(NAME)' file.yaml
|
||||
```
|
||||
|
||||
Merge multiple files
|
||||
```
|
||||
yq ea '. as $item ireduce ({}; . * $item )' path/to/*.yml
|
||||
```
|
||||
|
||||
Multiple updates to a yaml file
|
||||
```bash
|
||||
yq e -i '
|
||||
.a.b[0].c = "cool" |
|
||||
.x.y.z = "foobar" |
|
||||
.person.name = strenv(NAME)
|
||||
' file.yaml
|
||||
```
|
||||
|
||||
## Install
|
||||
|
||||
#### [Download the latest binary](https://github.com/mikefarah/yq/releases/latest)
|
||||
See the [github page](https://github.com/mikefarah/yq/#install) for the various ways you can install and use `yq`
|
||||
|
||||
### wget
|
||||
## Known Issues / Missing Features
|
||||
- `yq` attempts to preserve comment positions and whitespace as much as possible, but it does not handle all scenarios (see https://github.com/go-yaml/yaml/tree/v3 for details)
|
||||
- Powershell has its own...[opinions on quoting yq](https://mikefarah.gitbook.io/yq/usage/tips-and-tricks#quotes-in-windows-powershell)
|
||||
|
||||
Use wget to download the pre-compiled binaries:
|
||||
|
||||
#### Compressed via tar.gz
|
||||
|
||||
```bash
|
||||
wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY}.tar.gz -O - |\
|
||||
tar xz && mv ${BINARY} /usr/bin/yq
|
||||
```
|
||||
|
||||
#### Plain binary
|
||||
|
||||
```bash
|
||||
wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY} -O /usr/bin/yq &&\
|
||||
chmod +x /usr/bin/yq
|
||||
```
|
||||
|
||||
For instance, VERSION=v4.2.0 and BINARY=yq\_linux\_amd64
|
||||
|
||||
### Homebrew
|
||||
|
||||
[Homebrew](https://brew.sh) is a package manger for MacOS and Linux.
|
||||
|
||||
```
|
||||
brew install yq
|
||||
```
|
||||
|
||||
for the (deprecated) v3 version
|
||||
|
||||
```
|
||||
brew install yq@3
|
||||
```
|
||||
|
||||
Note that for v3, as it is a versioned brew it will not add the `yq` command to your path automatically. Please follow the instructions given by brew upon installation.
|
||||
|
||||
### Snap
|
||||
|
||||
Snap can be used on all major Linux distributions.
|
||||
|
||||
```
|
||||
snap install yq
|
||||
```
|
||||
|
||||
or, for the (deprecated) v3 version:
|
||||
|
||||
```
|
||||
snap install yq --channel=v3/stable
|
||||
```
|
||||
|
||||
**Snap notes**
|
||||
|
||||
`yq` installs 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 e '.a.path' -
|
||||
```
|
||||
|
||||
And to write to a root file you can either use [sponge](https://linux.die.net/man/1/sponge):
|
||||
|
||||
```
|
||||
sudo cat /etc/myfile | yq e '.a.path = "value"' - | sudo sponge /etc/myfile
|
||||
```
|
||||
|
||||
or write to a temporary file:
|
||||
|
||||
```
|
||||
sudo cat /etc/myfile | yq e '.a.path = "value"' | sudo tee /etc/myfile.tmp
|
||||
sudo mv /etc/myfile.tmp /etc/myfile
|
||||
rm /etc/myfile.tmp
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
**Oneshot use:**
|
||||
|
||||
```bash
|
||||
docker run --rm -v "${PWD}":/workdir mikefarah/yq <command> [flags] [expression ]FILE...
|
||||
```
|
||||
|
||||
**Run commands interactively:**
|
||||
|
||||
```bash
|
||||
docker run --rm -it -v "${PWD}":/workdir --entrypoint sh mikefarah/yq
|
||||
```
|
||||
|
||||
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 "$@"
|
||||
}
|
||||
```
|
||||
|
||||
### Go Get
|
||||
|
||||
```
|
||||
GO111MODULE=on go get github.com/mikefarah/yq
|
||||
```
|
||||
|
||||
## Community Supported Installation methods
|
||||
|
||||
As these are supported by the community :heart: - however, they may be out of date with the officially supported releases.
|
||||
|
||||
## Webi
|
||||
|
||||
```
|
||||
webi yq
|
||||
```
|
||||
|
||||
See [webi](https://webinstall.dev) for more infor.
|
||||
|
||||
Supported by @adithyasunil26 ([https://github.com/webinstall/webi-installers/tree/master/yq](https://github.com/webinstall/webi-installers/tree/master/yq))
|
||||
|
||||
### Chocolatey for Windows:
|
||||
|
||||
```
|
||||
choco install yq
|
||||
```
|
||||
|
||||
Supported by @chillum ([https://chocolatey.org/packages/yq](https://chocolatey.org/packages/yq))
|
||||
|
||||
### MacPorts:
|
||||
|
||||
```
|
||||
sudo port selfupdate
|
||||
sudo port install yq
|
||||
```
|
||||
|
||||
Supported by @herbygillot ([https://ports.macports.org/maintainer/github/herbygillot](https://ports.macports.org/maintainer/github/herbygillot))
|
||||
|
||||
### Alpine Linux
|
||||
|
||||
* Enable edge/community repo by adding `$MIRROR/alpine/edge/community` to `/etc/apk/repositories`
|
||||
* Update database index with `apk update`
|
||||
* Install yq with `apk add yq`
|
||||
|
||||
Supported by Tuan Hoang [https://pkgs.alpinelinux.org/package/edge/community/x86/yq](https://pkgs.alpinelinux.org/package/edge/community/x86/yq)
|
||||
|
||||
#### On Ubuntu 16.04 or higher from Debian package:
|
||||
|
||||
```bash
|
||||
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys CC86BB64
|
||||
sudo add-apt-repository ppa:rmescandon/yq
|
||||
sudo apt update
|
||||
sudo apt install yq -y
|
||||
```
|
||||
|
||||
Supported by @rmescandon ([https://launchpad.net/\~rmescandon/+archive/ubuntu/yq](https://launchpad.net/\~rmescandon/+archive/ubuntu/yq))
|
||||
|
||||
## Parsing engine and YAML spec support
|
||||
|
||||
Under the hood, yq uses [go-yaml v3](https://github.com/go-yaml/yaml/tree/v3) as the yaml parser, which supports [yaml spec 1.2](https://yaml.org/spec/1.2/spec.html). In particular, note that in 1.2 the values 'yes'/'no' are no longer interpreted as booleans, but as strings.
|
||||
See [tips and tricks](https://mikefarah.gitbook.io/yq/usage/tips-and-tricks) for more common problems and solutions.
|
||||
Loading…
Reference in New Issue
Block a user