diffyml

Install

Mon, 01 Jan 0001 00:00:00 +0000

Install#

Homebrew#

brew tap szhekpisov/diffyml
brew install diffyml

Go install#

go install github.com/szhekpisov/diffyml@latest

Make sure $GOPATH/bin is in your PATH:

export PATH="$(go env GOPATH)/bin:$PATH"

Docker#

Multi-arch images (linux/amd64, linux/arm64) are published to GitHub Container Registry:

docker pull ghcr.io/szhekpisov/diffyml:latest

# Compare two files from the current directory
docker run --rm -v "$PWD:/work" -w /work ghcr.io/szhekpisov/diffyml:latest old.yaml new.yaml

Images are built from a distroless base and run as a non-root user. Use :latest or pin to a specific version (e.g. :1.5.25).

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

Quick Start#

Five minimal examples that cover most of what you’ll do day-to-day.

Compare two local files#

diffyml old.yaml new.yaml

The default detailed format renders a colored, contextual diff in the terminal.

Compare two local directories#

diffyml dir-old/ dir-new/

diffyml walks both directories recursively, matches files by relative path, and shows aggregated differences. Non-YAML files are silently skipped.

Compare a local file against a remote URL#

diffyml local.yaml https://example.com/remote.yaml

from and to arguments accept HTTP/HTTPS URLs in addition to local paths.

Output Formats

Mon, 01 Jan 0001 00:00:00 +0000

Output Formats#

diffyml supports eight output formats. Pick one with -o / --output.

Format	Flag	Use case
detailed	`-o detailed` (default)	Human review — full context
compact	`-o compact`	Quick scan of changes
brief	`-o brief`	Counts only
github	`-o github`	GitHub Actions annotations
gitlab	`-o gitlab`	GitLab Code Quality JSON
gitea	`-o gitea`	Gitea CI annotations
json	`-o json`	Machine-readable, scriptable
json-patch	`-o json-patch`	RFC 6902 JSON Patch

detailed (default)#

Human-readable terminal output with colors, paths, and surrounding context. Best for interactive use.

CI Integration

Mon, 01 Jan 0001 00:00:00 +0000

CI Integration#

Exit codes#

-s / --set-exit-code is the building block for CI usage:

Exit code	Meaning
`0`	No differences (or success without `-s`)
`1`	Differences detected (only with `-s`)
`255`	Error occurred

diffyml -s before.yaml after.yaml || echo "Config drift detected"

GitHub Actions#

The recommended path is the diffyml-action composite action — no manual binary install needed.

- uses: szhekpisov/diffyml-action@v1
 with:
 from: old.yaml
 to: new.yaml

To inspect drift without failing the job, read the has-differences output:

Kubernetes Support

Mon, 01 Jan 0001 00:00:00 +0000

Kubernetes Support#

diffyml understands Kubernetes manifests by default. Resources are auto-detected and matched by apiVersion + kind + metadata.name (or metadata.generateName), so diffs stay meaningful even when document order changes.

diffyml manifests-v1.yaml manifests-v2.yaml

Rename detection#

When resources can’t be matched by identifier — for example, kustomize configMapGenerator hash-suffix changes like app-config-abc123 → app-config-def456 — diffyml pairs unmatched documents by content similarity (60% threshold) and shows field-level diffs instead of bulk add/remove.

Filtering & Chroot

Mon, 01 Jan 0001 00:00:00 +0000

Filtering & Chroot#

Two complementary mechanisms: filters narrow the output (which differences are shown), chroot narrows the input (which subtree is compared).

Filtering by path#

# Only changes under spec.replicas
diffyml --filter spec.replicas old.yaml new.yaml

# Exclude noisy paths
diffyml --exclude metadata.annotations old.yaml new.yaml

# Both flags are repeatable
diffyml --exclude status --exclude metadata.managedFields old.yaml new.yaml

Bracket syntax for keys with dots#

When a key itself contains ., wrap it in brackets:

Sensitive Value Masking

Mon, 01 Jan 0001 00:00:00 +0000

Sensitive Value Masking#

Masking is opt-in. When enabled, diffyml replaces matching values with a placeholder (default ***) before any output is rendered. The redacted value reaches every output format — detailed, compact, brief, github, gitlab, gitea, json, json-patch — and the AI summarizer prompt. Diffs still show that a value changed, just not what the value was.

Auto-mask Kubernetes Secret data#

--mask-secrets redacts the data and stringData fields of any document whose kind is Secret.

Configuration File

Mon, 01 Jan 0001 00:00:00 +0000

Configuration File#

diffyml loads project-level defaults from .diffyml.yml (or .diffyml.yaml) in the current directory. CLI flags override config file values. Use --config to specify a custom path.

diffyml --config /etc/diffyml/global.yml old.yaml new.yaml

Example#

# .diffyml.yml
output: compact
ignore-order-changes: true
detect-kubernetes: false
filter:
 - spec.containers
exclude:
 - status

All CLI flags map to config keys in kebab-case (matching the long flag name). Unknown keys are rejected to catch typos.

Full reference#

# Output
output: detailed  # detailed, compact, brief, github, gitlab, gitea, json, json-patch
color: auto  # always, never, auto
truecolor: auto  # always, never, auto

# Comparison
ignore-order-changes: false
ignore-whitespace-changes: false
format-strings: false
ignore-value-changes: false
detect-kubernetes: true
detect-renames: true
ignore-api-version: false
no-cert-inspection: false
swap: false

# Filtering (lists — CLI replaces these entirely if specified)
filter: []
exclude: []
filter-regexp: []
exclude-regexp: []
additional-identifier: []

# Display
omit-header: false
use-go-patch-style: false
multi-line-context-lines: 4

# Chroot
chroot: ""
chroot-of-from: ""
chroot-of-to: ""
chroot-list-to-documents: false

# Sensitive value masking (opt-in)
mask-secrets: false
mask-path: []
mask-path-regexp: []
mask-placeholder: "***"

# AI Summary (requires ANTHROPIC_API_KEY environment variable)
summary: false
summary-model: "claude-haiku-4-5-20251001"

# Exit code
set-exit-code: false

See Sensitive Value Masking for usage.

AI Summaries

Mon, 01 Jan 0001 00:00:00 +0000

AI Summaries#

Generate a natural-language summary of changes via the Anthropic API.

Setup#

Set your API key:

export ANTHROPIC_API_KEY="sk-ant-..."

Then run with --summary (or -S):

diffyml --summary old.yaml new.yaml

The summary is appended after the standard diff output. If the API call fails, a warning is printed to stderr and the diff output is preserved. The exit code is never affected by summary success or failure.

With other formats#

--summary composes with every output format. The notable variant: brief + summary swaps the bare counts for the AI description.

Reference

Mon, 01 Jan 0001 00:00:00 +0000

This page is auto-generated from pkg/diffyml/cli/flag_metadata.go by make docs-gen. Do not edit by hand — your changes will be overwritten on the next build.

diffyml [flags] <from> <to>

Output#

Flag	Type	Default	Description
`-o`, `--output`	`string`	`detailed`	specify output style: compact, brief, github, gitlab, gitea, json, json-patch, detailed
`-c`, `--color`	`string`	`auto`	specify color usage: always, never, or auto
`-t`, `--truecolor`	`string`	`auto`	specify true color usage: always, never, or auto

Comparison#

Flag	Type	Default	Description
`-i`, `--ignore-order-changes`	`bool`	—	ignore order changes in lists
`--ignore-whitespace-changes`	`bool`	—	ignore leading or trailing whitespace changes
`--format-strings`	`bool`	—	canonicalize embedded JSON strings before comparison
`-v`, `--ignore-value-changes`	`bool`	—	exclude changes in values
`--detect-kubernetes`	`bool`	`true`	detect kubernetes entities
`--detect-renames`	`bool`	`true`	enable detection for renames
`--ignore-api-version`	`bool`	—	ignore apiVersion when matching Kubernetes resources
`-x`, `--no-cert-inspection`	`bool`	—	disable x509 certificate inspection
`--swap`	`bool`	—	swap ‘from’ and ’to’ for comparison

Filtering#

Flag	Type	Default	Description
`--filter`	`list`	—	filter reports to a subset of differences (repeatable)
`--exclude`	`list`	—	exclude reports from a set of differences (repeatable)
`--filter-regexp`	`list`	—	filter reports using regular expressions (repeatable)
`--exclude-regexp`	`list`	—	exclude reports using regular expressions (repeatable)
`--additional-identifier`	`list`	—	use additional identifier in named entry lists (repeatable)

Neat#

Flag	Type	Default	Description
`--neat`	`bool`	—	exclude well-known noisy K8s/Helm/ArgoCD/Flux paths
`--no-neat-helm`	`bool`	—	with –neat: keep Helm-injected paths
`--no-neat-argocd`	`bool`	—	with –neat: keep ArgoCD-injected paths
`--no-neat-flux`	`bool`	—	with –neat: keep Flux-injected paths
`--no-neat-status`	`bool`	—	with –neat: keep .status subtree and spec.nodeName
`--neat-explain`	`bool`	—	print neat exclude regexes that fired (to stderr)
`--neat-strip-path`	`list`	—	additional regex appended to the neat bundle (requires –neat; repeatable)

Masking#

Flag	Type	Default	Description
`--mask-secrets`	`bool`	—	auto-mask data/stringData of Kubernetes Secret resources
`--mask-path`	`list`	—	additional path to mask (dot-notation, prefix match; repeatable)
`--mask-path-regexp`	`list`	—	additional path to mask (regex; repeatable)
`--mask-placeholder`	`string`	`***`	placeholder for masked values

Display#

Flag	Type	Default	Description
`-b`, `--omit-header`	`bool`	—	omit the diffyml summary header
`-g`, `--use-go-patch-style`	`bool`	—	use Go-Patch style paths in outputs
`--multi-line-context-lines`	`int`	`4`	context lines for multi-line strings

Chroot#

Flag	Type	Default	Description
`--chroot`	`string`	—	change the root level of the input file
`--chroot-of-from`	`string`	—	only change the root level of the from input file
`--chroot-of-to`	`string`	—	only change the root level of the to input file
`--chroot-list-to-documents`	`bool`	—	treat chroot list as set of documents

AI Summary#

Flag	Type	Default	Description
`-S`, `--summary`	`bool`	—	enable AI-powered summary of differences (requires ANTHROPIC_API_KEY)
`--summary-model`	`string`	`claude-haiku-4-5-20251001`	specify Anthropic model for summary

Configuration#

Flag	Type	Default	Description
`--config`	`string`	`.diffyml.yml`	path to config file

Other#

Flag	Type	Default	Description
`-s`, `--set-exit-code`	`bool`	—	set program exit code based on differences
`-h`, `--help`	`bool`	—	show help

Version#

Flag	Type	Default	Description
`-V`, `--version`	`bool`	—	show version information

--version is handled in main.go before flag parsing, so it works even when other arguments are missing or invalid.