zetl

Diff Command

zetl diff computes a graph-level diff against Git history, showing what changed in the link structure between two points in time.

Usage

# Diff against previous commit (default: HEAD~1)
zetl -d ./my-vault diff

# Diff against a specific ref
zetl diff --from main~5

# Diff by date
zetl diff --since "2026-02-01"

# Filter by change category
zetl diff --filter links

Flags

FlagDefaultDescription
--from <ref>HEAD~1Git ref to diff against
--since <datetime>noneFind closest commit at or before this date
--filter <category>noneFilter output: pages, links, orphans, dead_links

How it works

zetl uses an efficient reconstruction algorithm (see ADR-012 Changed Files Reconstruction):

  1. git diff --name-only identifies changed .md files between the baseline and HEAD
  2. git show retrieves the old content of each changed file
  3. Old content is parsed for wikilinks
  4. Set differences between old and new graphs yield the diff

This scales with the size of the change, not the size of the vault.

Output

The diff reports:

  • Pages added and removed
  • Links added and removed
  • Orphans gained and resolved
  • Dead links added and resolved

Design decision

zetl uses Git as its history backend rather than maintaining its own snapshots. See ADR-011 No Snapshots for the rationale. This is the only zetl command that requires Git.

See also: CLI Reference, Watch Command, Check Command, SPEC-007 Graph Diff

Backlinks