Machine Outputs

Four machine-readable formats, one flag: --format=json, --format=llm, --format=markdown, and --format=ndjson. All are stable and deterministic. Same input, same output.

JSON

differens main..feature --format=json prints one document with everything: the per-file narrated changes and the cross-file moves.

{
  "perFile": [
    {
      "description": "renamed function `computeTotal` to `calculateTotalAmount`",
      "filePath": "src/checkout.ts",
      "action": {
        "type": "Update",
        "node": { "kind": "function", "label": "calculateTotalAmount", "line": 12 },
        "detail": { "kind": "Renamed", "from": "computeTotal", "to": "calculateTotalAmount" },
        "context": [{ "kind": "class", "label": "Checkout" }]
      }
    }
  ],
  "crossFileMoves": [
    {
      "kind": "function",
      "name": "formatPrice",
      "fromFile": "src/old/utils.ts",
      "toFile": "src/new/utils.ts",
      "modified": false
    }
  ]
}

Schema notes:

perFile is an array of SemanticChange objects: description, filePath, and the full action (typed EditAction, containment context chain included, nearest ancestor first).
crossFileMoves is a flattened summary of kind, name, source, destination, and whether the node was edited in transit.
Hash values are serialized as integers. The JSON replacer handles bigint as a precaution, though hashes currently fit in 53-bit safe integers.

LLM

--format=llm is a compact, self-contained document. It costs less than the raw diff it replaces. Each named change gets one line, each file is named once, and unnamed churn collapses into a tally. Every named change carries its source line, so a model can read twenty lines of context instead of the whole file.

differens/1 2 files 5 changes 4 named
# src/checkout.ts
~ function computeTotal :12 < class Checkout computeTotal -> calculateTotalAmount
+ function applyDiscount :40
# src/cart.ts
* 2 comments
# cross-file
> formatPrice src/old/utils.ts -> src/new/utils.ts edited

Line grammar:

Part	Meaning
`differens/1 <files> files <changes> changes <named> named`	Header, one line
`# <path>`	File heading, named once
`+` `-` `~` `>`	Insert, Delete, Update, Move
`:12`	1-based source line of the change
`< class Checkout`	Nearest named ancestor scope
`from -> to`	Rename or value change
`* 2 comments`	Rolled-up minor changes (unnamed nodes, prose lines)
`# cross-file` / `> name from -> to [edited]`	Cross-file moves section

Pipe it straight into a model:

differens main..feature --format=llm | llm "summarize this changeset"

Renamed computeTotal to calculateTotalAmount inside Checkout, added
applyDiscount, and moved formatPrice from src/old/utils.ts to
src/new/utils.ts with minor edits.

Markdown

--format=markdown is a changelog you can drop into a PR description: one ## heading per file, one bullet per change.

## src/checkout.ts

- renamed function `computeTotal` to `calculateTotalAmount`
- added function `applyDiscount`

Empty changesets render as _no logical changes_.

NDJSON (streaming)

--format=ndjson is the streaming format: one JSON object per changed file, printed the moment that file’s diff finishes, always in input order. A long changeset starts producing output while the later files are still matching.

{"filePath":"src/checkout.ts","changes":[{"description":"renamed function `computeTotal` to `calculateTotalAmount`","action":{...}}]}

Per-line shape:

filePath: which file this object covers.
changes: narrated changes for that file, description plus the typed action, same shape as the perFile entries in the JSON format.
Unchanged files produce no line, matching the other formats.

Cross-file moves need the whole changeset, so when any exist they trail as one final object:

{"crossFileMoves":[{"kind":"function","name":"formatPrice","fromFile":"src/old/utils.ts","toFile":"src/new/utils.ts","modified":false}]}

Consumers filter per-file lines with select(.filePath) and read the trailer with select(.crossFileMoves).

differens main..feature --format=ndjson | jq -c 'select(.filePath) | .filePath'

Getting Started

How It Works

Guides

Machine Outputs

Machine Outputs

JSON

LLM

Markdown

NDJSON (streaming)

​Machine Outputs

​JSON

​LLM

​Markdown

​NDJSON (streaming)

Machine Outputs

JSON

LLM

Markdown

NDJSON (streaming)