δyƒƒ /ˈdʏf/

A diff tool for YAML files, and sometimes JSON

Description

dyff is inspired by the way the old BOSH v1 deployment output reported changes from one version to another by only showing the parts of a YAML file that change.

Each difference is referenced by its location in the YAML document by using either the Spruce or go-patch path syntax. The output report aims to be as compact as possible to give a clear and simple overview of the change.

Similar to the standard diff tool, it follows the principle of describing the change by going from the from input file to the target to input file.

Input files can be local files (filesystem path), remote files (URI), or the standard input stream (using -).

All orders of keys in hashes are preserved during processing and output to the terminal, most notably in the sub-commands to convert YAML to JSON and vice versa.

Installation

On macOS, dyff is available via Homebrew:

brew install homeport/tap/dyff

Prebuilt binaries for a lot of operating systems and architectures can be downloaded from the releases section.

There is a convenience script to download the latest release for Linux or macOS if you want to keep it simple (you need curl and jq installed on your machine):

curl --silent --location https://tinyurl.com/y4qvdl4d | bash

And of course, you can download and build dyff from source using go:

go get github.com/homeport/dyff/cmd/dyff

Use cases and examples

• Show the differences between two versions of cf-deployment YAMLs:

  dyff between \
    https://raw.githubusercontent.com/cloudfoundry/cf-deployment/v1.10.0/cf-deployment.yml \
    https://raw.githubusercontent.com/cloudfoundry/cf-deployment/v1.20.0/cf-deployment.yml

  

• Embed dyff into Git for better understandable differences

  # Setup...
  git config --local diff.dyff.command 'dyff_between() { dyff --color on between --omit-header "$2" "$5"; }; dyff_between'
  echo '*.yml diff=dyff' >> .gitattributes
  
  # And have fun, e.g.:
  git log --ext-diff -u
  git show --ext-diff HEAD

  

• Convert a JSON stream to YAML

  sometool --json | jq --raw-output '.data' | dyff yaml -

• Sometimes you end up with YAML or JSON files, where the order of the keys in maps was sorted alphabetically. With dyff you can restructure keys in maps to a more human appealing order:

  sometool --export --json | dyff yaml --restructure -

  Or, rewrite a file in place with the restructured order of keys.

  dyff yaml --restructure --in-place somefile.yml

• Just print a YAML (or JSON) file to the terminal to look at it. By default, dyff will use a neat output schema which includes different colors and indent helper lines to improve readability. The colors are roughly based on the default Atom schema and work best on dark terminal backgrounds. The neat output is disabled if the output of dyff is redirected into a pipe, or you can disable it explicitly using the --plain flag.

  dyff yaml somefile.yml

• Convert a YAML file to JSON and vice versa:

  dyff json https://raw.githubusercontent.com/cloudfoundry/cf-deployment/v1.19.0/cf-deployment.yml

  The dyff sub-command (yaml, or json) defines the output format, the tool automatically detects the input format itself.

  dyff yaml https://raw.githubusercontent.com/homeport/dyff/develop/assets/bosh-yaml/manifest.json