yq

Docker 拉取 Github 发布（按发布版本） CodeQL

一个轻量级和便携的命令行 YAML、JSON 和 XML 处理器。yq 使用类似 jq 的语法，但可以处理 yaml 文件以及 json、xml、properties、csv 和 tsv。它目前还不支持 jq 的所有功能，但支持最常用的操作和函数，并且正在不断添加更多功能。

yq 是用 go 编写的 - 所以你可以下载一个无依赖的二进制文件到你的平台上就可以使用了！如果你喜欢，还可以使用各种包管理器，以及 Docker 和 Podman，下面都有列出。

快速使用指南

读取一个值：

yq '.a.b[0].c' file.yaml

从 STDIN 管道输入：

yq '.a.b[0].c' < file.yaml

原地更新 yaml 文件：

yq -i '.a.b[0].c = "cool"' file.yaml

使用环境变量更新：

NAME=mike yq -i '.a.b[0].c = strenv(NAME)' file.yaml

合并多个文件：

# 合并两个文件
yq -n 'load("file1.yaml") * load("file2.yaml")'

# 使用通配符合并：
# 注意使用 `ea` 一次性评估所有文件
# 而不是按顺序评估
yq ea '. as $item ireduce ({}; . * $item )' path/to/*.yml

对 yaml 文件进行多次更新：

yq -i '
  .a.b[0].c = "cool" |
  .x.y.z = "foobar" |
  .person.name = strenv(NAME)
' file.yaml

在数组中查找并更新一个项目：

yq '(.[] | select(.name == "foo") | .address) = "12 cat st"'

将 JSON 转换为 YAML：

yq -Poy sample.json

更多示例请查看示例，更多信息请查看文档。

查看讨论区了解常见问题和有趣想法。

安装

下载最新的二进制文件

wget

使用 wget 下载 gzip 压缩的预编译二进制文件：

例如，VERSION=v4.2.0 和 BINARY=yq_linux_amd64

通过 tar.gz 压缩

wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY}.tar.gz -O - |\
  tar xz && mv ${BINARY} /usr/bin/yq

纯二进制文件

wget https://github.com/mikefarah/yq/releases/download/${VERSION}/${BINARY} -O /usr/bin/yq &&\
    chmod +x /usr/bin/yq

MacOS / Linux 通过 Homebrew：

使用 Homebrew

brew install yq

Linux 通过 snap：

snap install yq

Snap 注意事项

yq 在 snap 中以严格限制安装，这意味着它无法直接访问根文件。要读取根文件，你可以：

sudo cat /etc/myfile | yq '.a.path'

要写入根文件，你可以使用 sponge：

sudo cat /etc/myfile | yq '.a.path = "value"' | sudo sponge /etc/myfile

或者写入临时文件：

sudo cat /etc/myfile | yq '.a.path = "value"' | sudo tee /etc/myfile.tmp
sudo mv /etc/myfile.tmp /etc/myfile
rm /etc/myfile.tmp

使用 Docker 或 Podman 运行

一次性使用：

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

请注意，如果需要，你可以在没有网络访问权限和其他权限的情况下在 docker 中运行 yq，即 --security-opt=no-new-privileges --cap-drop all --network none。

podman run --rm -v "${PWD}":/workdir mikefarah/yq [command] [flags] [expression ]FILE...

通过 STDIN 管道输入：

你需要传递 -i\--interactive 标志给 docker：

docker run -i --rm mikefarah/yq '.this.thing' < myfile.yml

podman run -i --rm mikefarah/yq '.this.thing' < myfile.yml

交互式运行命令：

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

podman run --rm -it -v "${PWD}":/workdir --entrypoint sh mikefarah/yq

创建一个 bash 函数来避免输入整个 docker 命令会很有用：

yq() {
  docker run --rm -i -v "${PWD}":/workdir mikefarah/yq "$@"
}

yq() {
  podman run --rm -i -v "${PWD}":/workdir mikefarah/yq "$@"
}

以 root 身份运行：

yq 的容器镜像不再以 root 身份运行（https://github.com/mikefarah/yq/pull/860）。如果你想在容器镜像中安装更多东西，或者在尝试读取/写入文件时遇到权限问题，你需要：

docker run --user="root" -it --entrypoint sh mikefarah/yq

podman run --user="root" -it --entrypoint sh mikefarah/yq

或者，在你的 Dockerfile 中：

FROM mikefarah/yq

USER root
RUN apk add --no-cache bash
USER yq

缺少时区数据

默认情况下，yq 使用的 alpine 镜像不包含时区数据。如果你想使用 tz 操作符，你需要包含这些数据：

FROM mikefarah/yq

USER root
RUN apk add --no-cache tzdata
USER yq

带有 SELinux 的 Podman

如果你使用带有 SELinux 的 podman，你需要在卷挂载上设置共享卷标志 :z：

-v "${PWD}":/workdir:z

GitHub Action

  - name: Set foobar to cool
    uses: mikefarah/yq@master
    with:
      cmd: yq -i '.foo.bar = "cool"' 'config.yml'
  - name: Get an entry with a variable that might contain dots or spaces
    id: get_username
    uses: mikefarah/yq@master
    with:
      cmd: yq '.all.children.["${{ matrix.ip_address }}"].username' ops/inventories/production.yml
  - name: Reuse a variable obtained in another step
    run: echo ${{ steps.get_username.outputs.result }}

Go 安装：

go install github.com/mikefarah/yq/v4@latest

社区支持的安装方法

这些方法由社区支持 :heart: - 但可能与官方支持的版本不同步。

请注意，Debian 包（之前由 @rmescandon 维护）不再维护。请使用其他安装方法。

Nix

nix profile install nixpkgs#yq-go

参见这里

Webi

webi yq

参见 webi 由 @adithyasunil26 支持 (https://github.com/webinstall/webi-installers/tree/master/yq)

Arch Linux

pacman -S go-yq

Windows:

使用 Chocolatey

choco install yq

由 @chillum 支持 (https://chocolatey.org/packages/yq)

使用 scoop

scoop install main/yq

使用 winget

winget install --id MikeFarah.yq

Mac:

使用 MacPorts

sudo port selfupdate
sudo port install yq

由 @herbygillot 支持 (https://ports.macports.org/maintainer/github/herbygillot)

Alpine Linux

Alpine Linux v3.20+ (和 Edge)：

apk add yq-go

Alpine Linux 最高到 v3.19：

apk add yq

由 Tuan Hoang 支持 (https://pkgs.alpinelinux.org/packages?name=yq-go)

Flox:

Flox 可用于在 Linux、MacOS 和通过 WSL 的 Windows 上安装 yq。

flox install yq

特性

详细的文档和大量示例
使用可移植的Go语言编写，可下载无依赖的二进制文件
语法类似于jq，但可处理YAML、JSON和XML文件
完全支持多文档YAML文件
支持YAML前置元数据块（如Jekyll/Assemble）
彩色YAML输出
带时区的日期/时间操作和格式化
深层数据结构处理
键排序
操作YAML注释、样式、标签以及锚点和别名
原地更新
复杂表达式用于选择和更新
更新时保留YAML格式和注释（但空白处理存在问题）
解码/编码base64数据
从其他文件加载内容
与JSON/NDJSON互相转换
与XML互相转换
与属性文件互相转换
与CSV/TSV互相转换
通用shell补全脚本（bash/zsh/fish/powershell）
用于合并多个文件或数组求和等高级操作的Reduce功能
用于自动化流程的GitHub Action（感谢@devorbitus）

用法

查看文档以获取更详细和高级的用法。

用法：
  yq [标志]
  yq [命令]

示例：

# 如果未指定命令，yq默认使用'eval'命令。更多示例请参见"yq eval --help"。
yq '.stuff' < myfile.yml # 从"myfile.yml"输出"stuff"节点的数据

yq -i '.stuff = "foo"' myfile.yml # 原地更新myfile.yml


可用命令：
  completion       为指定的shell生成自动补全脚本
  eval             （默认）按顺序对每个YAML文件中的每个文档应用表达式
  eval-all         加载所有YAML文件的所有YAML文档并运行一次表达式
  help             获取任何命令的帮助

标志：
  -C, --colors                        强制使用彩色打印
  -e, --exit-status                   如果没有匹配项或返回null或false，则设置退出状态
  -f, --front-matter string           (extract|process) 将首个输入作为YAML前置元数据处理。Extract将提取YAML内容，process将对YAML内容运行表达式，保持剩余数据不变
      --header-preprocess             在处理表达式之前吸收任何头部注释和分隔符。（默认为true）
  -h, --help                          yq的帮助信息
  -I, --indent int                    设置输出的缩进级别（默认为2）
  -i, --inplace                       原地更新给定的第一个文件
  -p, --input-format string           [yaml|y|xml|x] 输入的解析格式。注意json是yaml的子集。（默认为"yaml"）
  -M, --no-colors                     强制不使用彩色打印
  -N, --no-doc                        不打印文档分隔符（---）
  -n, --null-input                    不读取输入，仅评估给定的表达式。用于从头开始创建文档。
  -o, --output-format string          [yaml|y|json|j|props|p|xml|x] 输出格式类型。（默认为"yaml"）
  -P, --prettyPrint                   美化打印，'... style = ""'的简写
  -s, --split-exp string              将每个结果（或文档）打印到名为(exp)的文件中。[exp]参数必须返回字符串。可以在表达式中使用$index作为结果计数器。
      --unwrapScalar                  解包标量，不带引号、颜色或注释打印值（默认为true）
  -v, --verbose                       详细模式
  -V, --version                       打印版本信息并退出
      --xml-attribute-prefix string   XML属性的前缀（默认为"+"）
      --xml-content-name string       XML内容的名称（如果没有属性名）。（默认为"+content"）

使用"yq [命令] --help"获取有关命令的更多信息。