Diff tasks on Mergeway

Compare the working tree with HEAD

Mon, 01 Jan 0001 00:00:00 +0000

Compare the working tree with `HEAD`

Run validation and inspect Git state first:

mergeway-cli validate
git status --short

To review unstaged tracked changes and untracked data while excluding staged-only content, use zero arguments:

mergeway-diff

This mode compares HEAD with an unstaged working-tree view. It is useful while continuing to edit after staging a known baseline. Untracked, non-ignored records matching configured includes are part of the view.

To review everything currently on disk against HEAD, pass HEAD explicitly:

Compare two Git revisions

Mon, 01 Jan 0001 00:00:00 +0000

Compare two Git revisions

Resolve the comparison endpoints, then pass both to Diff:

LEFT="$(git rev-parse HEAD~1)"
RIGHT="$(git rev-parse HEAD)"
mergeway-diff "$LEFT" "$RIGHT"

Both arguments must resolve to commits. Tags, branches, hashes, and Git revision expressions work. The command reads configuration and data from those commits and ignores every current staged, unstaged, and untracked file, making the result reproducible from the same repository history.

To compare a pull-request range locally, use the merge base rather than assuming the branch point:

Publish a semantic change summary

Mon, 01 Jan 0001 00:00:00 +0000

Publish a semantic change summary

Choose the most recent commit before the reporting window and verify that it exists:

BASELINE="$(git log -1 --before="7 days ago" --format="%H")"
test -n "$BASELINE" || { echo "No baseline commit found" >&2; exit 1; }
CURRENT="$(git rev-parse HEAD)"

Compare two explicit revisions so local work cannot leak into a published report:

mergeway-diff "$BASELINE" "$CURRENT"

Then assemble the result with its reproducible endpoints:

{
 echo "# Weekly semantic data update"
 echo
 echo "Baseline: $BASELINE"
 echo "Current: $CURRENT"
 echo
 echo '```text'
 mergeway-diff "$BASELINE" "$CURRENT"
 echo '```'
} > weekly-data-update.md

Review weekly-data-update.md before publishing it. The report describes record additions, removals, modifications, and relocations; it deliberately omits commit authorship and configuration-only edits. Pair it with your normal Git review when those details matter.

Consume JSON diff output in automation

Mon, 01 Jan 0001 00:00:00 +0000

Consume JSON diff output in automation

Capture a committed comparison as JSON:

mergeway-diff --format json HEAD~1 HEAD > semantic-diff.json

Check the schema version before consuming entries. With jq:

jq -e '.version == 1' semantic-diff.json >/dev/null
jq -r '.entries[] | [.kind, .type, .object_id] | @tsv' semantic-diff.json

Diff exits 0 for both empty and non-empty comparisons. Test the array when a workflow needs to branch:

if jq -e '.entries | length > 0' semantic-diff.json >/dev/null; then
 echo "Semantic changes found"
else
 echo "No semantic changes"
fi

Keep command failure separate from a non-empty result:

Troubleshoot semantic diff

Mon, 01 Jan 0001 00:00:00 +0000

Troubleshoot semantic diff

A revision cannot be resolved

Run git rev-parse <revision> in the same repository. mergeway-diff accepts Git revisions and the working-tree sentinel documented in the reference; it does not interpret arbitrary filesystem paths as revisions.

A snapshot cannot be loaded

Validate the relevant checked-out state with mergeway-cli validate. Diff must load configuration and records at both endpoints before comparing them. Missing configuration, malformed sources, or an invalid identifier can prevent snapshot construction.