ADR-011: No zetl-Managed Snapshots

Status: Accepted

Context

Diff Command needs a baseline to diff against. Should zetl maintain its own snapshot history, or delegate to Git?

Decision

zetl uses Git as the sole history backend. It does not maintain snapshot storage.

Rationale

Most vaults are already in Git repositories
Snapshot management adds significant storage and complexity
Git provides rich baseline selection: refs, tags, dates, HEAD~N
The Merkle Tree provides content-addressed change detection within a single point in time; Git provides the temporal axis

Trade-offs

zetl diff requires Git — it’s the only zetl command with this dependency
Vaults not in Git cannot use diff
Git must be installed and accessible on PATH

Mitigation

When Git is unavailable, zetl diff produces a clear error message explaining the requirement. All other commands continue to work. See SPEC-007 Graph Diff for the full specification.

Rationale

Trust — users adopt CLI tools more readily when they can’t cause data loss

Composability — read-only access means zetl works alongside Obsidian, Logseq, Foam, Dendron, or any editor without conflict

Simplicity — no write path means no write bugs, no file locking, no corruption recovery

Disposability — the cache is derived data; losing it costs only a re-index

# 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

Flag

Default

Description

--from <ref>

HEAD~1

Git ref to diff against

--since <datetime>

none

Find closest commit at or before this date

--filter <category>

none

Filter output: pages, links, orphans, dead_links

How it works

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

git diff --name-only identifies changed .md files between the baseline and HEAD

git show retrieves the old content of each changed file

Old content is parsed for wikilinks

Set differences between old and new graphs yield the diff

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

Requirement

REQ-046

Git ref baseline (--from <ref>)

REQ-047

Since-date baseline (--since <date>)

REQ-048

Default baseline (HEAD~1)

REQ-049

Structured diff output

REQ-050

Diff filter by category

REQ-051

Git unavailable error

REQ-052

Efficient reconstruction

Structure

Each file produces a flat list of Merkle leaf nodes, computed from pulldown-cmark AST block-level elements:

Leaf type

Source

Heading

## Section Title

Paragraph

Prose text blocks

SplBlock

```spl fenced code blocks

Code

Non-SPL fenced code blocks

Table

Markdown tables

List

Ordered/unordered lists

Blockquote

> block quotes

Frontmatter

YAML between --- fences

SPL dual hashing

SPL blocks receive two hashes:

content_hash — hash of the raw SPL text (changes on any edit, including comments)

ast_hash — hash of the parsed SPL AST (changes only on logical modifications)

The AST hash drives theory cache invalidation — see architecture/Cache. The content hash detects any change for drift purposes.

ADR-011: No zetl-Managed Snapshots

Context

Decision

Rationale

Trade-offs

Mitigation

Backlinks