mergeway-diff reference

This reference describes mergeway-diff v0.10.0 and repositories declaring mergeway.version: 1. It is a standalone binary, not a mergeway-cli subcommand.

Invocation and snapshot modes

mergeway-diff [flags]
mergeway-diff [flags] <left>
mergeway-diff [flags] <left> <right>

Each revision must resolve through Git to a commit. Branches, tags, full hashes, abbreviated hashes, and expressions such as HEAD~1 work when Git resolves them. More than two positional arguments is an input error.

The zero-argument view is not the same as git diff --cached: a staged-only edit is excluded. When a tracked file has both staged and unstaged edits, Diff reads the file currently on disk and compares that complete value with HEAD; it does not reconstruct only the lines added after staging.

Flags

What is compared

Diff loads the entity definitions and included data in each snapshot, normalizes records, and keys them by entity name plus logical identifier. It reports:

• added: the identity exists only on the right;
• removed: the identity exists only on the left;
• modified: the identity exists on both sides but one or more logical field values differ;
• relocated: values are unchanged but the source path or selector changed.

Nested map changes use dot-separated paths. Repeated values are compared semantically without regard to order. Entries and field changes are emitted deterministically. Configuration files are never emitted as change entries, although changing configuration can change which records are loaded or how they are interpreted.

Human-readable output

The default renderer uses uppercase change kinds and Entity[identifier] headings:

ADDED Post[post-002]
  at: data/posts/retrospective.yaml

MODIFIED Post[post-001]
  title: "Launch Day" -> "Launch Day reviewed"

REMOVED Comment[comment-001]
  from: data/comments/launch-comment.json

Added entries show at; removed entries show from; relocations show from and to. A modified entry shows source lines only when its source changed, followed by each changed field as JSON-encoded before -> after values. No differences produces exactly No changes. followed by a newline.

JSON output schema

--format json writes one JSON document followed by a newline. The top-level version is the output-schema version, currently 1; entries is always an array. This example is generated by the executable documentation check:

{
  "version": 1,
  "entries": [
    {
      "kind": "modified",
      "type": "User",
      "object_id": "user-alice",
      "old_value": {
        "email": "alice@example.com",
        "id": "user-alice",
        "name": "Alice Example",
        "roles": [
          "admin",
          "author"
        ]
      },
      "new_value": {
        "email": "alice@example.com",
        "id": "user-alice",
        "name": "Alice Reviewed",
        "roles": [
          "admin",
          "author"
        ]
      },
      "changes": [
        {
          "path": "name",
          "before": "Alice Example",
          "after": "Alice Reviewed"
        }
      ],
      "old_sources": [
        {
          "path": "data/users/alice.yaml"
        }
      ],
      "new_sources": [
        {
          "path": "data/users/alice.yaml"
        }
      ]
    }
  ]
}

Every entry contains kind, type, and object_id. Added and removed entries contain value and sources. Modified entries contain old_value, new_value, changes, old_sources, and new_sources. Relocated entries contain value, old_sources, and new_sources. A change has path, before, and after; a source has path and may have selector or read_only. Fields that do not apply are omitted. An empty semantic diff is {"version":1,"entries":[]} when whitespace is ignored.

Output, errors, and exit codes

Results go to standard output. Errors go to standard error as diff: <category>: <message>, where the category is input error, repository state error, data error, or internal error.

Success exits 0, including when differences are found and when no differences are found. Invalid arguments or revisions, a non-Git root, missing or invalid snapshot configuration, unreadable or unparseable data, duplicate logical identifiers, and internal failures exit 1 without a partial result. Diff therefore cannot be used as a “fail when different” check from its exit status alone; inspect JSON entries in automation.

Git prerequisites and limitations

• Git must be installed, --root must be inside a Git work tree, and HEAD plus every named revision must resolve to a commit.
• The configuration entry and included entity definitions must exist and be parseable in both snapshots. The data needed for the diff must also be parseable and have unique logical identifiers.
• Diff compares records; it does not report raw file hunks, configuration-only edits, commit metadata, authors, timestamps, or relationship-level validation results.
• Run mergeway-cli validate on the state you intend to publish. Diff’s loading checks do not replace full repository validation.
• JSON schema version 1 is stable output for v0.10.0, but consumers should reject unsupported versions and tolerate additional fields in compatible future output.
• --format currently treats only json specially; use the documented yaml or json values rather than relying on fallback behavior for another value.

Related documentation

Follow Review your first semantic change, learn how semantic comparison differs from a file diff, or choose a focused Diff how-to guide.