mikefarah/yq

yq

!https://github.com/mikefarah/yq/workflows/Build/badge.svg !Docker Pulls !Github Releases (by Release) !https://goreportcard.com/badge/github.com/mikefarah/yq

一款轻量级且可移植的命令行YAML处理器。

本项目旨在成为YAML文件的https://github.com/stedolan/jq%E6%88%96sed%E5%B7%A5%E5%85%B7%E3%80%82

V4版本已发布！

V4版本现已正式发布，与V3版本有较大差异（抱歉带来迁移成本），但它更接近jq，采用类似的表达式语法，因此支持更复杂的功能！

如果您一直在使用V3版本并希望/需要升级，请查看升级指南。

安装

Docker运行方式

一次性使用：

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

交互式运行命令：

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

创建bash函数可避免输入完整的docker命令，更为便捷：

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

其他安装方式（简要说明）

• 二进制下载：https://github.com/mikefarah/yq/releases/latest
• MacOS：使用Homebrew brew install yq
• Linux (snap)：snap install yq（注意严格限制模式下的文件访问方式）
• wget：下载预编译二进制到/usr/bin/yq并添加执行权限
• Go Get：GO111MODULE=on go get github.com/mikefarah/yq/v4

社区支持的安装方式（可能不是最新版本）：Windows (choco install yq)、MacPorts、Alpine Linux、Ubuntu (Debian包)等

核心功能和特性

• 使用可移植的Go语言编写，提供无依赖的独立二进制文件
• 采用类似jq的语法，适用于YAML和JSON文件处理
• 完全支持多文档YAML文件
• 彩色YAML输出
• 深度遍历YAML
• 按键排序YAML
• 操作YAML的注释、样式、标签和锚点
• 原地更新YAML
• 复杂表达式选择和更新
• 更新时保留YAML格式和注释（存在空白字符处理问题）
• JSON与YAML互转
• 通过'-'管道输入数据
• 通用shell补全脚本（bash/zsh/fish/powershell）

使用场景和适用范围

适用于需要在命令行环境中高效处理YAML文件的场景，包括但不限于：

• 配置文件的快速修改与查询
• 从YAML/JSON文件中提取特定数据
• YAML与JSON格式相互转换
• 批量处理多文档YAML文件
• 自动化脚本中集成YAML数据处理

详细使用方法

命令语法

yq [flags]
yq [command]

可用命令

• eval：对每个YAML文件中的每个文档应用表达式
• eval-all：加载所有YAML文件的所有文档并运行一次表达式
• help：获取命令帮助
• shell-completion：生成补全脚本

主要标志

使用示例

基本示例

bash
yq e '.a.b | length' f1.yml f2.yml 

Docker运行示例

一次性处理文件：

bash
docker run --rm -v "${PWD}":/workdir mikefarah/yq e '.a.b | length' f1.yml f2.yml

交互式运行：

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

已知问题/缺失功能

yq尝试尽可能保留注释位置和空白字符，但并非支持所有场景（详见：https://github.com/go-yaml/yaml/tree/v3%EF%BC%89

更多详细高级用法请参见官方文档。