suyiiyii/yq
1
0
Fork 0
mirror of https://github.com/mikefarah/yq.git synced 2026-07-10 00:05:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

cleanup: markdown

Browse Source
This commit is contained in:
Cory Latschkowski 2024-04-10 08:24:59 -05:00
parent fe84f62288
commit 77f1455125
1 changed files with 81 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

134
README.md
View File

@ -2,7 +2,6 @@
![Build](https://github.com/mikefarah/yq/workflows/Build/badge.svg) ![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) ![CodeQL](https://github.com/mikefarah/yq/workflows/CodeQL/badge.svg) ![Build](https://github.com/mikefarah/yq/workflows/Build/badge.svg) ![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) ![CodeQL](https://github.com/mikefarah/yq/workflows/CodeQL/badge.svg)
a lightweight and portable command-line YAML, JSON and XML processor. `yq` uses [jq](https://github.com/stedolan/jq) like syntax but works with yaml files as well as json, xml, properties, csv and tsv. 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, JSON and XML processor. `yq` uses [jq](https://github.com/stedolan/jq) like syntax but works with yaml files as well as json, xml, properties, csv and tsv. 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 and Podman, 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 and Podman, all listed below.
@ -10,26 +9,31 @@ yq is written in go - so you can download a dependency free binary for your plat
## Quick Usage Guide ## Quick Usage Guide
Read a value: Read a value:
```bash ```bash
yq '.a.b[0].c' file.yaml yq '.a.b[0].c' file.yaml
``` ```
Pipe from STDIN: Pipe from STDIN:
```bash ```bash
yq '.a.b[0].c' < file.yaml yq '.a.b[0].c' < file.yaml
``` ```
Update a yaml file, in place Update a yaml file, in place
```bash ```bash
yq -i '.a.b[0].c = "cool"' file.yaml yq -i '.a.b[0].c = "cool"' file.yaml
``` ```
Update using environment variables Update using environment variables
```bash ```bash
NAME=mike yq -i '.a.b[0].c = strenv(NAME)' file.yaml NAME=mike yq -i '.a.b[0].c = strenv(NAME)' file.yaml
``` ```
Merge multiple files Merge multiple files
```bash ```bash
# merge two files # merge two files
yq -n 'load("file1.yaml") * load("file2.yaml")' yq -n 'load("file1.yaml") * load("file2.yaml")'
@ -41,6 +45,7 @@ yq ea '. as $item ireduce ({}; . * $item )' path/to/*.yml
``` ```
Multiple updates to a yaml file Multiple updates to a yaml file
```bash ```bash
yq -i ' yq -i '
.a.b[0].c = "cool" | .a.b[0].c = "cool" |
@ -50,11 +55,13 @@ yq -i '
``` ```
Find and update an item in an array: Find and update an item in an array:
```bash ```bash
yq '(.[] | select(.name == "foo") | .address) = "12 cat st"' yq '(.[] | select(.name == "foo") | .address) = "12 cat st"'
``` ```
Convert JSON to YAML Convert JSON to YAML
```bash ```bash
yq -Poy sample.json yq -Poy sample.json
``` ```
@ -68,12 +75,13 @@ Take a look at the discussions for [common questions](https://github.com/mikefar
### [Download the latest binary](https://github.com/mikefarah/yq/releases/latest) ### [Download the latest binary](https://github.com/mikefarah/yq/releases/latest)
### wget ### wget
Use wget to download, gzipped pre-compiled binaries:
Use wget to download, gzipped pre-compiled binaries:
For instance, VERSION=v4.2.0 and BINARY=yq_linux_amd64 For instance, VERSION=v4.2.0 and BINARY=yq_linux_amd64
#### Compressed via tar.gz #### Compressed via tar.gz
```bash ```bash
wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY}.tar.gz -O - |\ wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY}.tar.gz -O - |\
tar xz && mv ${BINARY} /usr/bin/yq tar xz && mv ${BINARY} /usr/bin/yq
@ -93,101 +101,109 @@ wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O
chmod +x /usr/bin/yq chmod +x /usr/bin/yq
``` ```
### MacOS / Linux via Homebrew: ### MacOS / Linux via Homebrew
Using [Homebrew](https://brew.sh/) Using [Homebrew](https://brew.sh/)
```
```bash
brew install yq brew install yq
``` ```
### Linux via snap: ### Linux via snap
```
```bash
snap install yq snap install yq
``` ```
#### Snap notes #### 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: `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:
``` ```bash
sudo cat /etc/myfile | yq '.a.path' sudo cat /etc/myfile | yq '.a.path'
``` ```
And to write to a root file you can either use [sponge](https://linux.die.net/man/1/sponge): And to write to a root file you can either use [sponge](https://linux.die.net/man/1/sponge):
```
```bash
sudo cat /etc/myfile | yq '.a.path = "value"' | sudo sponge /etc/myfile sudo cat /etc/myfile | yq '.a.path = "value"' | sudo sponge /etc/myfile
``` ```
or write to a temporary file: or write to a temporary file:
```
```bash
sudo cat /etc/myfile | yq '.a.path = "value"' | sudo tee /etc/myfile.tmp sudo cat /etc/myfile | yq '.a.path = "value"' | sudo tee /etc/myfile.tmp
sudo mv /etc/myfile.tmp /etc/myfile sudo mv /etc/myfile.tmp /etc/myfile
rm /etc/myfile.tmp rm /etc/myfile.tmp
``` ```
### Run with Docker or Podman ### Run with Docker or Podman
#### Oneshot use:
#### Oneshot use
```bash ```bash
docker run --rm -v "${PWD}":/workdir mikefarah/yq [command] [flags] [expression ]FILE... docker run --rm -v "${PWD}":/workdir docker.io/mikefarah/yq [command] [flags] [expression] FILE...
``` ```
Note that you can run `yq` in docker without network access and other privileges if you desire, Note that you can run `yq` in docker without network access and other privileges if you desire,
namely `--security-opt=no-new-privileges --cap-drop all --network none`. namely `--security-opt=no-new-privileges --cap-drop all --network none`.
```bash ```bash
podman run --rm -v "${PWD}":/workdir mikefarah/yq [command] [flags] [expression ]FILE... podman run --rm -v "${PWD}":/workdir docker.io/mikefarah/yq [command] [flags] [expression] FILE...
``` ```
#### Pipe in via STDIN: #### Pipe in via STDIN
You'll need to pass the `-i\--interactive` flag to docker: You'll need to pass the `-i\--interactive` flag to docker:
```bash ```bash
docker run -i --rm mikefarah/yq '.this.thing' < myfile.yml docker run -i --rm docker.io/mikefarah/yq '.this.thing' < myfile.yml
``` ```
```bash ```bash
podman run -i --rm mikefarah/yq '.this.thing' < myfile.yml podman run -i --rm docker.io/mikefarah/yq '.this.thing' < myfile.yml
``` ```
#### Run commands interactively: #### Run commands interactively
```bash ```bash
docker run --rm -it -v "${PWD}":/workdir --entrypoint sh mikefarah/yq docker run --rm -it -v "${PWD}":/workdir --entrypoint sh docker.io/mikefarah/yq
``` ```
```bash ```bash
podman run --rm -it -v "${PWD}":/workdir --entrypoint sh mikefarah/yq podman run --rm -it -v "${PWD}":/workdir --entrypoint sh docker.io/mikefarah/yq
``` ```
It can be useful to have a bash function to avoid typing the whole docker command: It can be useful to have a bash function to avoid typing the whole docker command:
```bash ```bash
yq() { yq() {
docker run --rm -i -v "${PWD}":/workdir mikefarah/yq "$@" docker run --rm -i -v "${PWD}":/workdir docker.io/mikefarah/yq "$@"
} }
``` ```
```bash ```bash
yq() { yq() {
podman run --rm -i -v "${PWD}":/workdir mikefarah/yq "$@" podman run --rm -i -v "${PWD}":/workdir docker.io/mikefarah/yq "$@"
} }
``` ```
#### Running as root:
`yq`'s container image no longer runs under root (https://github.com/mikefarah/yq/pull/860). If you'd like to install more things in the container image, or you're having permissions issues when attempting to read/write files you'll need to either: #### Running as root
`yq`'s container image no longer runs under root (<https://github.com/mikefarah/yq/pull/860>). If you'd like to install more things in the container image, or you're having permissions issues when attempting to read/write files you'll need to either:
``` ```bash
docker run --user="root" -it --entrypoint sh mikefarah/yq docker run --user="root" -it --entrypoint sh docker.io/mikefarah/yq
``` ```
``` ```bash
podman run --user="root" -it --entrypoint sh mikefarah/yq podman run --user="root" -it --entrypoint sh docker.io/mikefarah/yq
``` ```
Or, in your Dockerfile: Or, in your Dockerfile:
``` ```bash
FROM mikefarah/yq FROM docker.io/mikefarah/yq
USER root USER root
RUN apk add --no-cache bash RUN apk add --no-cache bash
@ -195,10 +211,11 @@ USER yq
``` ```
#### Missing timezone data #### Missing timezone data
By default, the alpine image yq uses does not include timezone data. If you'd like to use the `tz` operator, you'll need to include this data: By default, the alpine image yq uses does not include timezone data. If you'd like to use the `tz` operator, you'll need to include this data:
``` ```bash
FROM mikefarah/yq FROM docker.io/mikefarah/yq
USER root USER root
RUN apk add --no-cache tzdata RUN apk add --no-cache tzdata
@ -209,12 +226,13 @@ USER yq
If you are using podman with SELinux, you will need to set the shared volume flag `:z` on the volume mount: If you are using podman with SELinux, you will need to set the shared volume flag `:z` on the volume mount:
``` ```bash
-v "${PWD}":/workdir:z -v "${PWD}":/workdir:z
``` ```
### GitHub Action ### GitHub Action
```
```bash
- name: Set foobar to cool - name: Set foobar to cool
uses: mikefarah/yq@master uses: mikefarah/yq@master
with: with:
@ -228,82 +246,90 @@ If you are using podman with SELinux, you will need to set the shared volume fla
run: echo ${{ steps.get_username.outputs.result }} run: echo ${{ steps.get_username.outputs.result }}
``` ```
See https://mikefarah.gitbook.io/yq/usage/github-action for more. See <https://mikefarah.gitbook.io/yq/usage/github-action> for more.
### Go Install: ### Go Install
```
```bash
go install github.com/mikefarah/yq/v4@latest go install github.com/mikefarah/yq/v4@latest
``` ```
## Community Supported Installation methods ## Community Supported Installation methods
As these are supported by the community :heart: - however, they may be out of date with the officially supported releases. As these are supported by the community :heart: - however, they may be out of date with the officially supported releases.
_Please note that the Debian package (previously supported by @rmescandon) is no longer maintained. Please use an alternative installation method._ _Please note that the Debian package (previously supported by @rmescandon) is no longer maintained. Please use an alternative installation method._
### Nix ### Nix
``` ```bash
nix profile install nixpkgs#yq-go nix profile install nixpkgs#yq-go
``` ```
See [here](https://search.nixos.org/packages?channel=unstable&show=yq-go&from=0&size=50&sort=relevance&type=packages&query=yq-go) See [here](https://search.nixos.org/packages?channel=unstable&show=yq-go&from=0&size=50&sort=relevance&type=packages&query=yq-go)
### Webi ### Webi
``` ```bash
webi yq webi yq
``` ```
See [webi](https://webinstall.dev/) See [webi](https://webinstall.dev/)
Supported by @adithyasunil26 (https://github.com/webinstall/webi-installers/tree/master/yq) Supported by @adithyasunil26 (<https://github.com/webinstall/webi-installers/tree/master/yq>)
### Arch Linux ### Arch Linux
``` ```bash
pacman -S go-yq pacman -S go-yq
``` ```
### Windows: ### Windows
Using [Chocolatey](https://chocolatey.org) Using [Chocolatey](https://chocolatey.org)
[![Chocolatey](https://img.shields.io/chocolatey/v/yq.svg)](https://chocolatey.org/packages/yq) [![Chocolatey](https://img.shields.io/chocolatey/v/yq.svg)](https://chocolatey.org/packages/yq)
[![Chocolatey](https://img.shields.io/chocolatey/dt/yq.svg)](https://chocolatey.org/packages/yq) [![Chocolatey](https://img.shields.io/chocolatey/dt/yq.svg)](https://chocolatey.org/packages/yq)
```
```bash
choco install yq choco install yq
``` ```
Supported by @chillum (https://chocolatey.org/packages/yq)
Supported by @chillum (<https://chocolatey.org/packages/yq>)
Using [scoop](https://scoop.sh/) Using [scoop](https://scoop.sh/)
```
```bash
scoop install main/yq scoop install main/yq
``` ```
Using [winget](https://learn.microsoft.com/en-us/windows/package-manager/) Using [winget](https://learn.microsoft.com/en-us/windows/package-manager/)
```
```bash
winget install --id MikeFarah.yq winget install --id MikeFarah.yq
``` ```
### Mac: ### Mac
Using [MacPorts](https://www.macports.org/) Using [MacPorts](https://www.macports.org/)
```
```bash
sudo port selfupdate sudo port selfupdate
sudo port install yq sudo port install yq
``` ```
Supported by @herbygillot (https://ports.macports.org/maintainer/github/herbygillot)
Supported by @herbygillot (<https://ports.macports.org/maintainer/github/herbygillot>)
### Alpine Linux ### Alpine Linux
- Enable edge/community repo by adding ```$MIRROR/alpine/edge/community``` to ```/etc/apk/repositories``` - Enable edge/community repo by adding ```$MIRROR/alpine/edge/community``` to ```/etc/apk/repositories```
- Update database index with ```apk update``` - Update database index with ```apk update```
- Install yq with ```apk add yq``` - Install yq with ```apk add yq```
Supported by Tuan Hoang Supported by Tuan Hoang
https://pkgs.alpinelinux.org/package/edge/community/x86/yq <https://pkgs.alpinelinux.org/package/edge/community/x86/yq>
## Features ## Features
- [Detailed documentation with many examples](https://mikefarah.gitbook.io/yq/) - [Detailed documentation with many examples](https://mikefarah.gitbook.io/yq/)
- Written in portable go, so you can download a lovely dependency free binary - Written in portable go, so you can download a lovely dependency free binary
- Uses similar syntax as `jq` but works with YAML, [JSON](https://mikefarah.gitbook.io/yq/usage/convert) and [XML](https://mikefarah.gitbook.io/yq/usage/xml) files - Uses similar syntax as `jq` but works with YAML, [JSON](https://mikefarah.gitbook.io/yq/usage/convert) and [XML](https://mikefarah.gitbook.io/yq/usage/xml) files
@ -331,7 +357,7 @@ https://pkgs.alpinelinux.org/package/edge/community/x86/yq
Check out the [documentation](https://mikefarah.gitbook.io/yq/) for more detailed and advanced usage. Check out the [documentation](https://mikefarah.gitbook.io/yq/) for more detailed and advanced usage.
``` ```bash
Usage: Usage:
yq [flags] yq [flags]
yq [command] yq [command]
@ -374,8 +400,10 @@ Flags:
Use "yq [command] --help" for more information about a command. Use "yq [command] --help" for more information about a command.
``` ```
## Known Issues / Missing Features ## 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)
- `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) - Powershell has its own...[opinions on quoting yq](https://mikefarah.gitbook.io/yq/usage/tips-and-tricks#quotes-in-windows-powershell)
- "yes", "no" were dropped as boolean values in the yaml 1.2 standard - which is the standard yq assumes. - "yes", "no" were dropped as boolean values in the yaml 1.2 standard - which is the standard yq assumes.