Clarify comparison and report controls

This commit is contained in:
Jan Petykiewicz 2026-11-19 10:21:56 -08:00
commit 623de2e585

View file

@ -127,21 +127,24 @@ pheon diff before.gds after.gds --hierarchy mermaid --depth 4
```
`--show-cell` and `--show-layer` filter displayed changes without changing the
comparison, totals, or exit status. A layer display filter hides references
without a numeric layer. `--max-changes N` limits displayed object occurrences
after filtering. Text defaults to 100 occurrences and shows a replacement only
when both objects fit within the limit. Grouped rows count each object toward
the limit. When a layer filter selects one side of a layer-only replacement,
that side appears as an addition or removal. A single omission line lists
changes hidden by filters or the limit. JSON has no default object limit and reports
omissions from both display filters and any explicit limit in `report_selection`.
See the [JSON reference](diff-reports.md) for the selection counters.
comparison, totals, or exit status. In text reports, `--show-layer` filters
object changes within modified cells and hides references without a numeric
layer. Added and removed cells appear as name-only entries outside the object
budget. Use `--show-cell` to filter those entries.
`--max-changes N` limits displayed object occurrences after filtering. Text
defaults to 100 occurrences and shows a replacement only when both objects fit
within the limit. Grouped rows count each object toward the limit. When a
layer filter selects one side of a layer-only replacement, that side appears as
an addition or removal. The omission line lists changes hidden by filters or the
limit. JSON has no default object limit and records omissions in
`report_selection`. See the [JSON reference](diff-reports.md) for the selection
counters.
`--details` shows individual object evidence inside modified cells in text
reports. Replacement rows include a nested `-` row for the old object and a
`+` row for the new object, with cell-local coordinates in database units,
retained fields, and properties. Both sides count toward `--max-changes`.
For added and removed cells, the report lists the cell name.
retained fields, and properties.
The diff hierarchy shows directly changed cells, affected ancestors, and targets
of modified references. It includes references from both revisions so removed