John O'Keefe
b3a8cbd582
Owner ruling that closed the scan-semantics discussion: the code is
correct (per-library scan IS a force scan — hx-vals force:true since
706be09d), but the label hid that. Now the naming invariant holds
everywhere: anything with Force/Rescan in its name re-reads everything
in its scope; plain 'Scan' only exists at folder scope ('Scan this
folder', shallow) and in auto mode. Book-level Rescan verified as the
per-item force path (extractMetadata re-reads sidecars/tags regardless
of file size; recomputeHashInfo follows) — it is the documented answer
to 'I changed this book's sidecar'.
Glossary Scan entry replaced with Force Rescan (old label kept in also:),
scanning.md table + prose pick up the new label. Generated file
regenerated with the Dockerfile-pinned templ version from inside
templates/ so the diff is exactly the label strings.
5.0 KiB
5.0 KiB
Scanning
Scanning is how Bookhoard's server reads your library folders and keeps the catalog in step with the files on disk. This page covers every scan an admin can trigger, what each one actually does, and what it costs — so you can pick the right one before clicking.
The one distinction: shallow vs. force
Every scan is one of two kinds:
- Shallow (the default). The scanner walks the folder and skips any file whose size and modification time are unchanged since it was last seen. New and changed files get processed; untouched files cost nothing. Fast, and the right choice for day-to-day keeping-up.
- Force. Nothing is skipped. Every file is re-read and re-extracted with the scanner's current parsing, and each item's hash identifiers (the SHA-256 fingerprints used for duplicate detection and device book matching) are recomputed. This is the backfill tool: run it after scanner improvements you want applied to already-scanned books, after mass edits in Calibre or on disk, or when metadata looks stale anywhere in a library. It is deliberately slow on big libraries.
Every scan control, and what it does
| Control | Where | Kind | Scope |
|---|---|---|---|
| Force Rescan All Libraries | Admin dashboard → Quick Actions | Force | Every library |
| Force Rescan (library row) | Admin → Libraries | Force | That library |
| Scan this folder (folder-row icon) | Admin → Libraries → a library's panel | Shallow | That folder's subtree |
| Auto-Scan + Scan Interval (seconds) | Admin → Settings → Scanning | Shallow | Every library |
| Retry / Retry all | Admin → Libraries → Processing Issues | Per-item | Failed items only |
| Rescan / Reset to Scanned | A book's detail page | Per-item | That one item |
The details behind the table:
- Force Rescan All Libraries loops over every library and starts a force scan job for each. Libraries that already have a scan running are left alone — the button reports which libraries started and which were skipped because a scan was already in flight.
- Force Rescan on a library row is the same force rescan, scoped to that one library. It shares the dashboard button's semantics exactly.
- Scan this folder is the only folder-sized scan, and the only shallow one an admin triggers by hand: unchanged files are skipped, and only that folder's subtree is walked. Because a partial scan can't vouch for what it didn't look at, it never marks items from the library's other folders as missing. Podcast download folders refuse this button — they are managed by the feed system, not the scanner.
- Auto-Scan arms the two automatic triggers, both shallow: a filesystem watcher that fires as files change, and a periodic poll that runs every Scan Interval (seconds) (default 60, allowed 1–3600). The same shallow pass also runs once at startup when auto-scan is on.
- Retry and Retry all on a library's Processing Issues page send failed items back through the scanner one at a time — deliberately not a library-wide scan, so fixing a few bad files never re-reads the whole library.
- Rescan on a book's page re-extracts that item from its file and recomputes its hashes. Reset to Scanned clears your manual metadata edits first, so what lands is purely what the scanner derives from the file.
Rules worth knowing
- One scan per library at a time. Starting a second scan for a library that already has one pending or running is refused — the dashboard tells you a scan is active rather than stacking a duplicate. The automatic triggers skip silently instead.
- Scans run in the background. The dashboard's Scanning panel shows per-library progress while jobs run; Cancel all scans stops the ones still queued or running, and you can keep working meanwhile.
- Missing files archive after two consecutive scans. When a library-wide scan (shallow or force) can't find a file twice in a row, the item is archived — reading history is kept in case the file comes back. The Archived Items page in this section manages the results.
- Metadata comes from the files themselves. The scanner reads sidecar
files (Calibre's
metadata.opfin particular), embedded tags, and filenames — Calibre Integration covers the sidecar story. What a scan extracts is exactly what a force rescan re-extracts.