Diff

What roar diff is

Two runs that should have matched didn't. A model regressed, a metric moved, an output that used to be byte-identical now isn't. roar diff answers why — it compares the full upstream lineage of two artifacts (or jobs, or sessions) and reports what actually differs, ranked so the likely root cause is at the top.

It's the CLI counterpart to the Diff view on glaas.ai (see Use Cases). Same idea, in your terminal, against your local .roar/roar.db.

roar diff ./model.pkl ./model-v2.pkl

Because artifacts are identified by content hash and every job records its inputs, code commit, arguments, and environment, roar can walk both lineage DAGs and diff them structurally — it isn't guessing from filenames or timestamps.

What you can compare

Either side of the diff can be any reference that resolves to a point in the lineage:

roar diff @5 @7                              # two steps in the current session
roar diff ./model.pkl deadbeefcafebabe       # a local file vs. an artifact by hash
roar diff session:current session:<hash>     # a whole pipeline vs. an earlier run

A bare artifact hash resolves locally first and can fall back to GLaaS when glaas.query_nonlocal_ids_on_glaas = true, so you can diff against a run you never had locally.

Reading the output

roar diff groups differences into categories and leads with a root-cause line. A representative diff after changing an input file:

Diff: metrics.json vs metrics.json
  A: 8e4607689a92eaa7...
  B: 60158676b881ab21...

ROOT CAUSE: Step @1: input 'raw.csv' has different content

INPUTS (root artifacts differ)
  A only: raw.csv  14a2d45d722f...
  B only: raw.csv  d2315ecb74d9...

CODE
  Step @1: code changed   A: 8f3eff4a   B: ad5a7476 [0.85]

UNCHANGED
  environment (same packages)
  parameters (same arguments)

The categories roar divides divergence into:

• Inputs — root (unsourced) artifacts whose content hash differs. A different dataset or a hand-edited config lands here.
• Code — the git commit recorded for a step differs. Note this is commit-level: two runs on different commits are reported as "code changed" even if the specific script for that step was byte-identical between them.
• Parameters — the command-line arguments to a step differ.
• Environment — the captured interpreter or package set differs.
• Pipeline — the DAG shape itself differs (a step added, removed, or rewired).

Each reported difference carries an impact score; roar ranks by it so the change most likely to explain the divergence surfaces first as the ROOT CAUSE.

Options

roar diff @5 @7 --json          # machine-readable output for scripts / CI
roar diff @5 @7 --depth 3       # cap how far up the lineage DAG to walk

When to reach for it

• A run regressed. Diff the bad output against the last good one; the root-cause line usually names the changed input, commit, or argument directly.
• "It works on my machine." Diff your session against a teammate's registered session to surface an environment or code drift.
• Auditing a promotion. Before shipping model-v2, diff it against model-v1 to confirm only the things you intended to change actually changed.