v0.5.0

Documentation

• Documentation greatly expanded: new dedicated pages for Installation, Examples, Remote Sources, Guides, and Troubleshooting; richer use-case descriptions; API page updated with tested code snippets; CLI reference reordered to match dirplot -h.

Changed

• read-meta renamed to meta — dirplot read-meta is now dirplot meta. The new command
  also gains a --json flag that outputs structured JSON with fields file, has_metadata,
  created, version, command, os, and python. Multiple files return a JSON array.
  Human-readable output now uses friendlier labels (Created:, Version: instead of Date:,
  Software:). Breaking change.

• --size renamed to --canvas in map, diff, watch, git, hg, and replay — the
  old flag controlled output pixel dimensions (e.g. --canvas 1920x1080). The name was freed up
  so that --size can be used for file-size filtering (see below). Breaking change.

Fixed

• Several correctness and robustness fixes: archive stat modes now include file type bits; watch mode SVG snapshots now render change highlights; diff summary counts respect --include; --workers rejects non-positive values; the watch_events.py script ignores its own output file when placed inside a watched directory; GitHub tokens are no longer embedded in clone URLs; and various edge-case fixes across the k8s, S3, and animation subsystems.

Added

• --size/-S file-size filter — available on map, diff, watch, and replay. Filters the
  scanned tree to files whose byte size matches a range. Syntax: 10M..500M (between 10 MiB and
  500 MiB), 100M.. (≥ 100 MiB), ..50K (≤ 50 KiB), 1G (exactly 1 GiB). Units: B K KB M MB G GB T TB (powers of 1024, case-insensitive). Repeatable — multiple --size flags combine
  with OR logic. Pass --keep-empty-dirs to retain directories that become empty after filtering.
  Filtering is post-scan; parent directory sizes are recalculated after pruning.

• watch improvements:

  • --event-log renamed to --output/-o — the JSONL event log is now the primary named
    output of watch, consistent with all other commands. Breaking change.
  • --append-event-log renamed to --append — shorter flag to append to an existing log
    instead of truncating on startup.
  • Continuous event-log flushing — events are flushed to --output after each regeneration
    (debounce window) rather than only at exit, so the log is safe against crashes or SIGKILL.
  • --highlight/-H — highlight matching paths with a coloured border, same syntax as
    map and diff. Patterns are re-evaluated on every regeneration.
  • --include — show only a named subtree, same as the map command.
  • --debounce validation — negative values are now rejected with an error.
  • --snapshot help text clarified: PNG or SVG; best for small trees as rendering adds
    latency on large directories.
  • Signal handling fixed — removed a stray signal.signal(SIGINT, SIG_IGN) call in the
    cleanup path that was unnecessarily suppressing Ctrl-C globally during shutdown.

• --log-scale validation — values ≤ 1 (including negative values) are now rejected with an
  error in all commands (map, diff, watch, git, hg, replay). Previously, invalid
  values were silently ignored. The programmatic API (apply_log_sizes) raises ValueError.

• --highlight/-H flag — available on map, diff, git, hg, and replay. Draws a
  coloured border around tiles whose paths match a pattern. Accepts exact paths or glob patterns
  including ** (e.g. src/**/*.py). Append @color to set the border colour
  (e.g. --highlight "**/*.py@orange"); defaults to red. Repeatable — each --highlight
  can target a different set of paths with its own colour. Works for both files and directories.
  Renders in both PNG and SVG output. In diff, user highlights are layered on top of the
  diff colour-coding. In git and hg, highlights appear in every animation frame.
  Colour names and hex codes accepted (any value supported by Pillow / CSS).

• Highlight step in dirplot demo — the demo now includes a map tests/ example that
  highlights a single file (conftest.py@red), a glob (**/test_git*.py@cyan), and a folder
  (tests/fixtures@lime) to demonstrate the feature.

• replay shows full directory context by default — the initial frame now includes all files
  in the watched directory tree, not just those that appear in the event log. Files touched during
  recording use the first logged size as their baseline; untouched files use a live stat. Pass
  --changed-only to revert to the old behaviour (event-log files only), which is faster for large
  trees where the surrounding context is not needed.