# yq — jq for YAML, JSON, XML, TOML, and .properties

> yq is the `jq` for YAML. It reads/writes YAML, JSON, XML, TOML, and properties files with jq-compatible syntax — essential for DevOps, CI pipelines, and any config-heavy workflow.

## Install

Save in your project root:

# yq — jq for YAML (and JSON/XML/TOML)

## Quick Use
```bash
# macOS
brew install yq
# Linux
sudo snap install yq
# Docker
docker run --rm -i mikefarah/yq < file.yaml

# Query
yq '.spec.replicas' deployment.yaml
# Update in place
yq -i '.spec.replicas = 5' deployment.yaml
# Merge two files
yq ea '. as $item ireduce ({}; . * $item )' base.yaml patch.yaml
```

## Introduction
yq (Mike Farah's Go version — the most popular fork) brings jq's legendary query language to YAML, JSON, XML, TOML, .properties, and CSV. If you've ever had to patch a Kubernetes manifest or grab a value from a Helm chart, yq is the tool.

With over 15,000 GitHub stars, yq is essentially required for any DevOps pipeline that touches YAML. It's a single Go binary with no dependencies, runs everywhere, and handles the multi-document + comments + anchors quirks that make YAML hard.

## What yq Does
yq applies jq-like expressions to structured documents. Read values, set values, delete keys, merge files, convert between formats (YAML ↔ JSON ↔ XML ↔ TOML), traverse with path expressions — everything `jq` does for JSON, plus format-specific features like preserving YAML comments and anchors.

## Architecture Overview
```
Input file (YAML/JSON/XML/TOML/properties)
      |
[Parser — choose decoder]
      |
[Expression Evaluator]
   jq-compatible syntax:
   .key, .[0], .[], |, select, map, reduce, as, ireduce
      |
[Mutations]
   assign, delete, merge (with *+ or ea)
      |
[Encoder]
   output in any supported format
   preserves comments + anchors (YAML)
      |
Stdout or in-place update (-i)
```

## Self-Hosting & Configuration
```bash
# Read nested values
yq '.metadata.labels.app' k8s/deploy.yaml

# Multi-value / array access
yq '.spec.template.spec.containers[].image' k8s/deploy.yaml

# Update and write back (preserves comments!)
yq -i '.spec.replicas = 10 | .metadata.labels.env = "prod"' k8s/deploy.yaml

# Merge patches (Kustomize-style)
yq ea '. as $item ireduce ({}; . * $item)' base.yaml overlay.yaml > merged.yaml

# Convert formats
yq -oj '.' config.yaml > config.json    # YAML -> JSON
yq -p json -oy '.' data.json > data.yaml  # JSON -> YAML
yq -p xml -oy '.' feed.xml > feed.yaml    # XML -> YAML

# Delete fields matching a pattern
yq -i 'del(.spec.template.spec.containers[].resources)' deploy.yaml

# Set values from shell vars
IMAGE="myorg/api:v1.2.3" yq -i '.spec.containers[0].image = strenv(IMAGE)' deploy.yaml
```

## Key Features
- **Multi-format** — YAML, JSON, XML, TOML, .properties, CSV
- **jq-compatible syntax** — path expressions, pipes, select, map, reduce
- **In-place edits** — `-i` flag preserves comments, anchors, formatting
- **Multi-document YAML** — handle `---` separator files natively
- **Merge + patch** — compose configs, overlay environments
- **Format conversion** — one flag changes output encoding
- **strenv / env helpers** — pull values from shell environment
- **Cross-platform** — single Go binary on macOS/Linux/Windows

## Comparison with Similar Tools
| Feature | yq (mikefarah) | yq (kislyuk / Python) | jq | yj | dasel |
|---|---|---|---|---|---|
| Languages | Go | Python | C | Go | Go |
| YAML | Yes | Yes | No | Yes | Yes |
| JSON | Yes | Yes (jq) | Yes | Yes | Yes |
| XML/TOML/.properties | Yes | Partial | No | No | Yes |
| In-place edit | Yes | Yes | No (you redirect) | No | Yes |
| Syntax | jq-compat | Calls jq | jq | jq wrapper | Own DSL |
| Best For | DevOps YAML | Python pipelines | Pure JSON | JSON<->YAML | Polyglot with own DSL |

## FAQ
**Q: Which yq do I want — mikefarah or kislyuk?**
A: Usually mikefarah's Go version (`brew install yq`). Kislyuk's Python version is a jq-wrapper — pick it only if you want strict jq semantics and are fine with a Python runtime. Most CI/CD uses mikefarah's.

**Q: Does yq preserve YAML comments?**
A: Yes — mikefarah's version preserves comments, anchors, and formatting on in-place edits. That's one of its biggest advantages for config management.

**Q: Can I use yq in a GitHub Actions workflow?**
A: Yes. `yq` is pre-installed on GitHub-hosted runners. Use `yq -i '...'` to patch manifest files before deploying.

**Q: What about very large YAML files?**
A: Multi-document YAML (thousands of `---` separated docs) works but can be slow. For very large files, consider `yq -e` to evaluate per-document or pipe through `--split-exp`.

## Sources
- GitHub: https://github.com/mikefarah/yq
- Docs: https://mikefarah.gitbook.io/yq
- Author: Mike Farah
- License: MIT

---
Source: https://tokrepo.com/en/workflows/a6b08736-380a-11f1-9bc6-00163e2b0d79
Author: AI Open Source