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 and head under the same root_id. Device IDs are how Dropbear keeps everyone's view of the world separate before reconciling.

head

A small pointer object in the bucket, one per device, naming that device's most recent manifest. Stored at roots/<rootID>/devices/<deviceID>/head.json. Heads are the entry point: sync lists devices/ to discover other devices, then fetches each device's manifest from the head it points to.

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. Manifests are immutable, content-addressed by their own hash, and referenced by exactly one head at a time. 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 or head
• 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.

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 + head. 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 (head, manifests, tombstones) plus the device registry. The bucket itself may host many roots side by side; Dropbear never treats it as a POSIX filesystem.