Diff two snapshots¶

Goal. Produce a human-readable changelog that describes what changed between two snapshots of a dataset.

Prerequisites. binoc installed (pip install binoc or uvx binoc …). Nothing else.

The one-liner¶

binoc diff path/to/snapshot-a path/to/snapshot-b

By default this prints a Markdown changelog to stdout. That's usually what you want at a terminal.

What the output looks like¶

For a dataset that ships as a zip of CSVs alongside a SQLite database:

# Changelog: release-q3/ → release-q4/

## Clerical Changes

- **data.zip/agencies.csv**: Columns reordered (content unchanged)

## Substantive Changes

- **summary.sqlite**: Content changed (12.0 KB → 12.0 KB)

Binoc looked inside the zip and compared the CSV column by column — the reorder is flagged as a clerical change (housekeeping), not a real data change. The .sqlite file is opaque to the standard library, so you only learn the bytes differ. To get semantic SQLite diffing, see Install and use plugins.

Choose an output format¶

The --format flag switches the stdout renderer. The two built-ins are markdown (the default) and json (raw changeset IR):

binoc diff A B                    # Markdown to stdout (default)
binoc diff A B --format json      # raw changeset JSON to stdout

A third-party plugin may register additional renderers (for example an HTML renderer); reference it by name.

Save outputs to files¶

-o/--output is repeatable. Each value is either format:path (explicit format) or a bare path (format inferred from extension):

binoc diff A B -o changeset.json -o CHANGES.md

Suppress stdout with -q when every output is going to a file:

binoc diff A B -o changeset.json -q

For the full story on output routing, see Save and render changesets and Output routing and CLI UX ADR.

Common issues¶

"Content changed" with no detail¶

If binoc reports only Content changed (X bytes → Y bytes) for a file, it means no comparator claimed the file's extension and it fell through to the binary catch-all. That's the signal to install a plugin that understands the format (see Install and use plugins) or to write one (see Write a Python comparator).

Where to go next¶

Save and render changesets — write JSON and Markdown artifacts, combine several changesets into one changelog.
Extract changed data — pull actual changed rows or lines out of a changeset.
Tutorial — a longer guided walkthrough of directory, zip, CSV, and plugin diffs.