Add diffyml as a backend (alongside dyff)

[szhekpisov]

Description

Add -o diffyml as a third output format, alongside the existing diff and dyff backends.

Motivation

kubectl-diff-watch already supports dyff as a structural-diff backend. diffyml is a similar YAML-aware diff library with a few properties that fit this plugin well:

• Single module dependency (yaml.v3) — much lighter dep tree than dyff, which matters for a kubectl plugin distributed via krew.
• Kubernetes-aware — matches resources by apiVersion + kind + name/generateName, handles --ignore-api-version for API migrations, detects renames by content similarity.
• Inline word-level highlighting in the default formatter.
• Performance — ~1.5–9× faster than dyff on the benchmarks in PERFORMANCE.md, which adds up when watching frequently-changing resources.

For the watch use case specifically, the K8s-aware matching is mostly a no-op (single resource, identity stable), but the lighter dependency footprint and inline highlighting are concrete wins.

Proposed UX

kubectl diff-watch deployment myapp -o diffyml

Mirroring how -o dyff is wired today.

Implementation

diffyml exposes a library API at github.com/szhekpisov/diffyml/pkg/... (see pkg.go.dev). Happy to open the PR myself if you're open to it.

And thanks for the plugin — it's a nice tool!

[databus23]

Thanks for the well-written proposal and for the kind words about the plugin!

I've thought about this, but I'm not sure a third output backend carries its weight here. A few considerations:

• Dependency footprint: The lighter dep tree is a real advantage of diffyml, but it only materializes if it replaces dyff rather than being added alongside it. As a third option, we'd actually be growing the dependency surface.
• Performance: The benchmarks look good, but in practice this tool spends most of its time waiting on the Kubernetes API and the human reading the output. I doubt the diff rendering step is a perceptible bottleneck.
• Word-level highlighting: This is genuinely nice and the most visible improvement for users. But it's a single feature, not necessarily a reason for a whole new backend.

I'd be more open to a conversation about replacing dyff with diffyml (trading one dep for a lighter one with better highlighting), but I'm hesitant to add and maintain a third code path for incremental benefit.

Does that make sense? Is there a specific pain point you hit with dyff output that motivated this?

[szhekpisov]

Hi @databus23 , thank you for considering my request!

I'll be honest, it's not about pain points, it's more about pitching a better engine for structured YAML comparison. Indeed, as you are pointing out, performance is not a concern. However, apart from dependency footprint and word-level highlighting, diffyml can also offer:

• Secrets masking.
• Better structure recognition for K8s resources — e.g. generateName-based identity.
• Neat options.
• Enables colour options for people with a colour vision deficiency.

One more thing I'd like to mention — diffyml has a stronger security posture (CodeQL + govulncheck + fuzz on every commit; plus a higher OpenSSF Scorecard rating).

I'm happy to answer any other questions, if there are any. But if you think it's not worth it — no hard feelings, I understand!