Materialized Views

Dropbear can keep a folder's full namespace visible while leaving most of its bytes in the bucket. The on-disk tree becomes a materialized view of what your peers have shared: every path is present, but a file's contents are only materialized — fetched and written to disk — when you ask for them. It's the same "online-only files" idea the hosted services ship, built on plain extended attributes and the content-addressed blob store, with no kernel extension or proprietary filesystem.

The mechanism is shelving: a file is either materialized (real bytes on disk) or shelved (a stub). dropbear fetch materializes; dropbear shelve goes back the other way.

How It Works

Dropbear marks shelved files with a filesystem extended attribute (user.dropbear.shelved on Linux, net.tfks.dropbear.shelved on macOS). The state database records each shelved entry's sha256 and size from the peer's manifest. When you run dropbear fetch, dropbear reads the sha256, downloads the blob from object storage, and atomically replaces the stub.

In .dropbear/root.toml, the optional default_download field controls what happens during sync when a peer publishes entries you don't have locally:

# Possible values: "" (absent), "materialize", "shelve"
default_download = "shelve"

absent / "materialize" (default): fetch blob bytes immediately (existing behavior).
"shelve": write a zero-byte stub with the marker xattr; skip the blob GET.

If default_download = "shelve" and the filesystem doesn't support extended attributes (e.g. a FAT32 USB stick), dropbear logs a warning and falls back to materialize for that run.

Materialize On-Demand

dropbear fetch <root> <path>...

Fetches one or more shelved files. Paths can be:

A single relative path: docs/report.pdf
A directory (recursive): photos/2024/
A glob: docs/*.pdf

A shelved file that is already clean is a no-op (idempotent). A modified file is skipped with a warning (exit 1) — fetch only materializes shelved entries.

Exit codes:

0 — all paths materialized (or already clean)
1 — one or more paths skipped (warning)
64 — bad argument (unknown path, path outside root, invalid glob)
65 — I/O failure writing materialized content
66 — blob fetch failure

Use --json for machine-readable output (schema_version: 1).

Free Space On-Demand

dropbear shelve [--force] [--no-verify] <root> <path>...

Converts clean files back to shelved stubs, reclaiming local disk space while keeping the entry visible in the tree. Before truncating, dropbear verifies that the blob is reachable in object storage (skip with --no-verify).

Only clean files can be shelved by default.
--force also allows shelving modified files (the local edits are discarded; make sure you've synced first).
--no-verify skips the bucket HEAD check (use when offline).

Exit codes: mirror dropbear fetch.

Shelved Restoration

dropbear restore --shelve <root>

Restores a root from a peer's manifest but writes stubs instead of downloading blobs. The directory tree is fully populated; no blob bytes are fetched. Incompatible with --force.

Shelve by Default

dropbear register --shelve-by-default ...

Creates root.toml with default_download = "shelve". Fails if the filesystem doesn't support extended attributes.

Shelve On-Demand

Override the root.toml default for a single sync run:

dropbear sync --shelve-new <root>
dropbear sync --materialize-new <root>

These flags are mutually exclusive.

Shelving & Sync Modes

Shelving is orthogonal to the four sync modes (bidirectional, upload-only, download-only, archive-only):

In upload-only mode the download phase is skipped, so default_download has no effect.
In download-only and bidirectional modes, default_download applies to every peer entry you don't have locally.
In archive-only mode, tombstones are applied but new blobs are not fetched; shelving is also suppressed.

Shelf Status

dropbear status shows a shelved bucket:

files       142 total
            100 clean
             40 new
              2 shelved (8.2 GB unmaterialized)

The drift check also verifies that every shelved entry's blob is present in the bucket. A missing blob means the stub cannot be materialized on demand and is reported as a blob-missing drift issue.

Platform notes

Linux: xattrs require a filesystem mounted with user_xattr (ext4, btrfs, XFS default to enabled).
macOS: xattrs work on APFS and HFS+; Finder shows no cloud icon (no OS hook).
FAT32 / exFAT / NTFS without xattr support: shelving is unavailable; dropbear falls back to materialize with a warning.