Diff tools
Versions of elements and code, and the change sets between them. This group has 4 tools, 1 of them available only with spec-editor Pro.
| Tool | Edition | Summary |
|---|---|---|
changeset_get |
Open core | Build a ChangeSet: first-before/last-after deltas for every element touched within a scope. |
code_at |
Pro | Read one file’s content from git — by blob sha (a code ElementDelta’s before_hash/after_hash, path-independent) or by rev (+ path). |
element_at |
Open core | Get one stored version of an element by its blob hash: the parsed element plus its raw markdown text. |
element_versions |
Open core | List one element’s version history: for each version, seq/ts/run_id/agent/action/before_hash/after_hash, plus the element’s current_hash. |
changeset_get
Build a ChangeSet: first-before/last-after deltas for every element touched within a scope. scope_kind is one of: element (an element’s full history), run (one run’s touched elements), run_tree (a run + its delegated descendants), change (an IMP: itself + runs whose brief carried its change_id + elements derived_from/resolves/tested_by it), gate (= change of the gate’s element id), deployment (= change of the deployment’s change_id attribute), window (since_ts/until_ts, optionally agent — no scope_id). include_content=false (default) omits the body diff.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
agent |
string | no | Filter to versions written by this agent key. |
include_code |
boolean | no | Union in code deltas (git-backed; default true). See ElementDelta.kind: ‘element’ vs ‘code’. |
include_content |
boolean | no | Include each delta’s body content_diff (default false). |
project_path |
string | yes | Path to spec-editor project (directory with methodology.yaml) |
scope_id |
string | no | Element/run id the scope resolves against. Required for every scope_kind except ‘window’. |
scope_kind |
string | yes | One of: [‘change’, ‘deployment’, ‘element’, ‘gate’, ‘run’, ‘run_tree’, ‘window’]. |
since_ts |
string | no | ISO-8601 lower bound (inclusive) on version ts. |
until_ts |
string | no | ISO-8601 upper bound (inclusive) on version ts. |
code_at
Pro tool. Available with the spec-editor Pro plugin.
Read one file’s content from git — by blob sha (a code ElementDelta’s before_hash/after_hash, path-independent) or by rev (+ path). Exactly one of blob/rev is required. Binary content returns an error.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
blob |
string | no | Git blob sha — reads the blob directly. |
path |
string | yes | File path (repo-relative). Required with ‘rev’. |
project_path |
string | yes | Path to spec-editor project (directory with methodology.yaml) |
repo |
string | no | Code repo label from local.yaml: code: repos. Omit when only one repo is configured. |
rev |
string | no | Git revision (commit/ref) — reads ‘path’ at it. |
element_at
Get one stored version of an element by its blob hash: the parsed element plus its raw markdown text. Hashes come from element_versions or a ChangeSet’s before_hash/after_hash.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
element_id |
string | yes | Element id this version belongs to (informational). |
hash |
string | yes | The blob’s sha256 hex digest (before_hash/after_hash). |
project_path |
string | yes | Path to spec-editor project (directory with methodology.yaml) |
element_versions
List one element’s version history: for each version, seq/ts/run_id/agent/action/before_hash/after_hash, plus the element’s current_hash. Read-only; returns an empty list if the element has no recorded versions.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
element_id |
string | yes | Element id. |
project_path |
string | yes | Path to spec-editor project (directory with methodology.yaml) |