Glossary

Terms used throughout the Dropbear docs and CLI output. If something here disagrees with the code, the code wins — please open an issue.

root

A directory on disk that Dropbear manages. Each root has its own .dropbear subdirectory containing root.toml (identity + remote config) and state.sqlite (local index). A single machine can have multiple roots, each pointing at its own bucket prefix. The root is the unit of sync — Dropbear never spans roots, and a missing root is treated as offline, never as "everything was deleted." See also device.

device

A named participant in a root. Identified by device_id in root.toml. Two laptops syncing the same photos root are two devices; each publishes its own manifest under the same root_id. Device IDs are how Dropbear keeps everyone's view of the world separate before reconciling.

manifest

A JSON snapshot of every tracked path in a root as one device saw it at the moment it last synced. Contains the relative path, mode, size, hash, symlink target, and so on for each entry. Each device publishes its current manifest at the canonical key roots/<rootID>/devices/<deviceID>/manifest.json, overwriting the prior object in place; peers read this key directly to discover that device's latest view. Dropbear uses full snapshots, not deltas — see the manifest-full-snapshots ADR.

blob

The actual bytes of a file, stored once in the bucket under roots/<rootID>/blobs/<ab>/<cd>/<sha256> (sharded by the first two hex byte-pairs to avoid S3 hot-prefix behaviour). Blobs are content-addressed: identical contents on multiple devices upload exactly one blob. A manifest entry references a blob by its hash; the path-to-blob mapping lives in the manifest, never in the blob's key.

hash

A SHA-256 digest, hex-encoded. Used as the address of a blob, as the integrity check on download, and as the identity of a manifest. Dropbear hashes whole files in the MVP; chunked hashing is on the roadmap but not implemented.

mode

The sync policy for a root, set in root.toml and load-bearing at runtime. One of:

• bidirectional — full upload + download + tombstone exchange (the default)
• upload-only — push local changes, ignore other devices entirely
• download-only — pull remote changes, never publish a manifest
• archive-only — pull remote changes but never delete locally; remote tombstones are recorded as applied without touching the filesystem

See use cases for the full phase-by-mode matrix.

conflict

What happens when this device and another device both changed the same path since the last common state. Dropbear does not merge. Instead it writes the remote content alongside the local copy as <stem>.conflict-<otherDeviceID>-<UTC-ts><ext>, flips the local row to StatusConflict, and publishes neither version in this device's next manifest until the user resolves it (typically by picking one, deleting the other, and re-syncing). Directory collisions, multi-device disagreement, and entries missing the required payload fall back to skip-with-warning rather than materializing a conflict file.

tombstone

An explicit delete record. When a tracked file disappears locally (and the previous scan saw it — Dropbear will not infer deletion from a single missing observation), sync writes a tombstone object at roots/<rootID>/devices/<deviceID>/tombstones/<seq>.json (zero-padded per-device monotonic sequence) and clears the row from state. Peers enumerate tombstones on their next sync and apply them according to the safety table: clean local with matching hash → remove; diverged → conflict-skip with warning; archive-only mode → record as applied without deleting. Tombstones exist because S3 has no "this path used to exist and is now gone" signal short of explicit metadata.

drift

A discrepancy between a manifest and the bucket's actual contents — specifically, a manifest entry whose blob is missing from the roots/<rootID>/blobs/ subtree. Surfaced by dropbear status for this device's manifest and for every other device's reachable manifest. Drift usually means someone ran a lifecycle policy, a manual s3 rm, or a garbage-collection pass that didn't account for current references. It is not self-healing; you have to re-upload or restore.

materialized view

A root whose tree is fully populated with paths but whose file contents are fetched on demand rather than all at once. Every entry a peer published is visible (you can ls, browse, and reason about the namespace), but a given file's blob bytes only land on disk when you fetch it — or immediately, if the root materializes by default. The opposite of a materialized file is a shelved one. The model is the same "online-only files" idea as the hosted services, but built on plain extended attributes and the content-addressed store, with no kernel extension. See Materialized views.

shelve

To turn a materialized file back into a zero-byte stub, reclaiming local disk while keeping the path visible in the materialized view. A shelved file carries a marker extended attribute (user.dropbear.shelved on Linux, net.tfks.dropbear.shelved on macOS); its hash and size are remembered in local state so it can be re-fetched later. dropbear shelve <root> <path>... does this for clean files (and, with --force, modified ones), verifying the blob is reachable in the bucket first so the stub stays materializable. A root can also shelve every new peer entry by default via default_download = "shelve" in root.toml. Filesystems without xattr support (FAT32, exFAT) can't shelve; Dropbear falls back to materializing with a warning.

fetch

To materialize a shelved file: read its hash from local state, download the blob, verify it, and atomically replace the stub with real bytes. dropbear fetch <root> <path>... accepts a path, a directory (recursive), or a glob, and is idempotent — fetching an already-materialized file is a no-op. Fetch only acts on shelved entries; a locally modified file is skipped with a warning. This is the on-demand half of a materialized view.

scan / plan / sync

Three verbs, often confused:

• scan walks the root and updates the local SQLite state with what's actually on disk. Read-only with respect to the bucket.
• plan classifies each tracked path (clean / new / modified / deleted / conflict / ignored) and prints what sync would do. Read-only with respect to both disk and bucket.
• sync does the work: downloads missing/changed remote blobs, materializes conflict files, applies remote tombstones, uploads local blobs, publishes a new manifest. Gated by mode.

status (of a path)

The classification a row carries in the local state table. One of:

• clean — on disk, matches the last published manifest.
• new — on disk, never published.
• modified — on disk, differs from the last published manifest.
• deleted — absent on disk this scan, present last scan and in the last manifest. The next sync emits a tombstone for it.
• tombstoned — a tombstone has been published (locally or by another device whose tombstone was applied here). The row is kept so a later stale remote manifest can't resurrect the file.
• conflict — local edit collides with a remote edit; resolution is pending. Neither version publishes until the user resolves it.
• ignored — matches a .dropbearignore pattern; not synced.
• error — last operation on this path failed in a way that needs human attention.

dropbear status aggregates these into counts; dropbear plan shows them per-path.

offline (root)

The state of a root whose directory is not currently present — typically a removable drive that's unplugged. Dropbear detects this via root.toml and refuses to do anything that would interpret the absence as data loss. Offline is not deletion. This is the single most important safety invariant in the project; see the removable-root-offline ADR.

bucket / prefix

The S3-compatible object store and the key prefix under which Dropbear keeps a root's data. Everything for a root lives under roots/<rootID>/ — blobs/ for content-addressed bytes and devices/ for per-device subtrees (manifests, tombstones) plus the device registry. The bucket itself may host many roots side by side; Dropbear never treats it as a POSIX filesystem.