# 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](/glossary#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`](#materialize-on-demand) materializes; [`dropbear shelve`](#free-space-on-demand) 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:

```toml
# 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.