Semantic diff of two files: what changed, by path, ignoring key order and formatting.

Reads JSON, JSONC, YAML (safe subset, multi-document supported), TOML, .env and INI files (format is detected from the file name; a and b may be different formats). Returns {identical, summary{added, removed, changed, type_changed, moved, total}, changes[], warnings[]}. Each change has an op ('added', 'removed', 'changed', 'type_changed', 'moved'), a JSONPath-like path such as $.servers[id=3].port, and old/new values (truncated to max_value_chars). A value going from 1 to "1" is type_changed; null versus a missing key is reported as a key that was added or removed, never as a change.

Args: a, b: file paths (relative paths resolve against the first --dir). format: json, jsonc, yaml, toml, env, ini, csv, or auto (from the extension). array_match: how list items are paired. 'auto' (default) matches lists of objects by the first of array_keys that is present and unique in every item, and falls back to position; 'index' pairs by position; 'key' is like auto but warns when no key works; 'set' ignores order and duplicates-aware compares items by value (good for tag lists). Items matched by key that changed position are reported as 'moved'. array_keys: candidate key fields, default ["id", "name", "key"]. ignore: patterns of paths to skip. '' matches any text, including dots and brackets: '$.metadata.updatedAt', '$.items[].etag', '.timestamp'. Must start with '$' or ''. abs_tol, rel_tol: numbers within these tolerances are treated as equal (0.1+0.2 vs 0.3 needs abs_tol=1e-9). 1 and 1.0 are always equal; big integers stay exact. strip_comments: remove // and /* */ comments and trailing commas before parsing JSON (always on for .jsonc). encoding: 'auto' honours UTF-8/16/32 BOMs, otherwise UTF-8; or give e.g. 'cp1252'. max_changes: cap on listed changes; summary counts are always complete.

Semantic diff of two pasted strings (same output and options as diff_files).

Use this for content that is not on disk. 'format' is required because it cannot be guessed from a name. Both strings must be in the same format. See diff_files for the output shape and for array_match, array_keys, ignore, abs_tol, rel_tol and strip_comments. For CSV text each row becomes an object, so array_keys can match rows by id; use csv_diff on files for large CSVs.

Row-level diff of two CSV/TSV files: added, removed and changed rows, per-cell changes, columns.

Rows are paired by key_columns (e.g. ["id"] or ["country", "year"]); without key_columns whole rows are compared as an unordered set, so an edited row appears as one removed plus one added row. Reports added/removed columns separately (cells of those columns are not compared) and whether the common columns were reordered. Duplicate keys are paired in file order and reported as a warning. The delimiter (, ; tab |) and BOM/UTF-16 encodings are detected automatically. File a is indexed in memory (limit 2 million rows); file b is streamed.

Args: a, b: file paths. key_columns: column names identifying a row; they must exist in both files. ignore_columns: column names or globs (e.g. "updated_*") whose cells are not compared. delimiter: a single character; auto-detected when omitted. abs_tol, rel_tol: numeric cells (both sides parse as numbers) within tolerance are equal; requires key_columns. max_changes: cap on entries in each of added_rows, removed_rows and changed_rows; summary counts are always complete.

Generate an RFC 6902 JSON Patch that transforms document a into document b.

The patch is verified before it is returned: it is applied to a and the result is re-diffed against b (using the same options), so a patch that does not reproduce b is never returned. Lists are patched with remove/add/move so keyed items keep their identity. With ignore or tolerance options the patched a equals b only up to those options. NaN/Infinity cannot be expressed in JSON and are rejected.

Args: a, b: file paths, or the documents themselves when inputs='text'. inputs: 'files' (default) or 'text'; text requires an explicit format. format, array_match, array_keys, ignore, abs_tol, rel_tol, strip_comments, encoding: as in diff_files.

Preview what an RFC 6902 JSON Patch does to a document, without writing anything.

Supports add, remove, replace, move, copy and test. Returns the patched document and a semantic summary of what changed versus the original. A failing operation is reported with its index and reason, and nothing is returned in that case.

Args: a: file path, or the document itself when inputs='text'. patch: the patch as a JSON array (or a JSON string of one). inputs, format, strip_comments, encoding: as in diff_files. max_result_chars: the result is cut off after this many characters (the summary is not).

Check how a file parses before diffing it: format, encoding, top-level shape, warnings.

Surfaces things that make diffs surprising: duplicate keys (JSON, YAML, .env), multi-document YAML, comments in JSON, an unexpected delimiter or encoding in CSV. For CSV it reports the columns, the detected delimiter and the row count (streamed, so large files are fine).