# 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). ## device A named participant in a [root](#root). Identified by `device_id` in `root.toml`. Two laptops syncing the same `photos` root are two devices; each publishes its own [manifest](#manifest) and [head](#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](#device), naming that device's most recent [manifest](#manifest). Stored at `roots//devices//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](#root) as one [device](#device) saw it at the moment it last synced. Contains the relative path, mode, size, [hash](#hash), symlink target, and so on for each entry. Manifests are immutable, content-addressed by their own hash, and referenced by exactly one [head](#head) at a time. Dropbear uses full snapshots, not deltas — see the [manifest-full-snapshots ADR](https://git.tfks.net/tfks/dropbear/wiki/decisions/manifest-full-snapshots). ## blob The actual bytes of a file, stored once in the bucket under `roots//blobs///` (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](#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](#blob), as the integrity check on download, and as the identity of a [manifest](#manifest). Dropbear hashes whole files in the MVP; chunked hashing is on the roadmap but not implemented. ## mode The sync policy for a [root](#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](/use-cases) for the full phase-by-mode matrix. ## conflict What happens when this [device](#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 `.conflict--`, 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//devices//tombstones/.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](#manifest) and the bucket's actual contents — specifically, a manifest entry whose [blob](#blob) is missing from the `roots//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](#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](#blob), materializes [conflict](#conflict) files, applies remote [tombstones](#tombstone), uploads local blobs, publishes a new [manifest](#manifest) + [head](#head). Gated by [mode](#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](#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](#scan--plan--sync) emits a [tombstone](#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](#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](https://git.tfks.net/tfks/dropbear/wiki/decisions/removable-root-offline). ## bucket / prefix The S3-compatible object store and the key prefix under which Dropbear keeps a [root](#root)'s data. Everything for a root lives under `roots//` — `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.