Skip to content

Diff and export workspaces

Compare two snapshots and write the change set between them to a file. A diff runs a Merkle-tree comparison of the two root trees, so unchanged directories are skipped without scanning their children (spec §5.6).

Both awcctl snapshot diff and awcctl snapshot export call the same endpoint, GET /v1/snapshots/{left}:diff?right={right} (spec §13.14). The first snapshot id is the old, left side. The second is the new, right side. An add-file entry means the path exists in the new side only. A delete-path entry means it exists in the old side only.

Before you start: point awcctl at the control plane with --control-endpoint (or AWC_CONTROL_ENDPOINT) and --token (or AWC_TOKEN). The call needs the export permission, and both snapshots MUST belong to your tenant.

  1. List your snapshots and copy the two ids.

    awcctl snapshot list

    Pick the older snapshot as the old, left side. Pick the newer snapshot as the new, right side.

  2. Print the change list to the terminal.

    awcctl snapshot diff snap_01J... snap_01K...

    Pass the old snapshot first and the new snapshot second. Each line shows the change kind and the path:

    modify-file   src/main.rs
add-file      docs/new.md
delete-path   tmp/old.log

    Add --output json to print the full structured DiffResponse.

  3. Export the change set to a file. Pass --format json.

    awcctl snapshot export snap_01J... \
  --against snap_01K... \
  --format json \
  --out changes.json

    export takes the same two sides as diff, in the same order. The first positional id is the old, left side. --against is the new, right side. --out writes the raw response bytes; - writes to standard output.

  4. Inspect the exported file.

    jq '.result.changes[] | {kind, path}' changes.json

    The file holds a DiffResponse. The inline form puts the list at result.changes[]. Each change carries kind, path, and the mode and content digest of the affected entry.

Only json is served today

The control plane serves --format json only. If you pass patch-bundle or tar, the API rejects the request with INVALID_ARGUMENT. The renderers for all three formats are implemented, but patch-bundle and tar are not wired to the HTTP endpoint. The default export format is patch-bundle, so you MUST pass --format json until the other formats ship.

Direction matches diff

export <left> --against <right> computes the same diff as diff <left> <right>. The change list goes from the old side to the new side. The flag name --against reads like a base, but in the wired code it is the new, right side. Pass the snapshots in the same order for both commands and the directions agree.

See also