docs: document persistence requirement for state files

Update documentation to clarify that beespoint.ini is only used and
beescrawl.dat is only migrated when state.persistent = yes is
configured.

Also update outdated references to beescrawl.dat in how-it-works.md
and running.md to reflect the current primary use of beespoint.ini.

Assisted-by: Gemini:gemini-3.5-flash
Signed-off-by: Zygo Blaxell <bees@furryterror.org>

diff --git a/docs/config.md b/docs/config.md
index 42c1f83b048b5c068a8944495d21949ec6e20f22..ccd02b601cf7930a390abb7b1c03fff269660f96 100644 (file)
--- a/docs/config.md
+++ b/docs/config.md
@@ -246,11 +246,11 @@ the filesystem and estimate an ETA for completion within each size
 tier; however, the accuracy of the ETA can be questionable due to the
 non-uniform distribution of block addresses in a typical user filesystem.
 
-Older versions of bees do not recognize the virtual subvols, so running
-an old bees version after running a new bees version will reset the
-"extent" scan mode's progress in `beescrawl.dat` to the beginning.
-This may change in future bees releases, i.e. extent scans will store
-their checkpoint data somewhere else.
+Bees stores extent scan checkpoint data in `beespoint.ini` using the
+named sections above.  If `state.persistent = yes` is configured, on
+first run after upgrading from an older bees version, checkpoint data from
+the old `beescrawl.dat` format is automatically migrated to
+`beespoint.ini`.
 
 The `--workaround-btrfs-send` option behaves differently in extent
 scan modes:  In extent scan mode, dedupe proceeds on all subvols that are

diff --git a/docs/how-it-works.md b/docs/how-it-works.md
index 542edc38d08d5a4c60f2cf8ef9ac1f8988e0f3d8..f3d01e22778bd9c24ff7b1809c4b293fa2951fef 100644 (file)
--- a/docs/how-it-works.md
+++ b/docs/how-it-works.md
@@ -7,7 +7,7 @@ across crashes and reboots.
 bees uses checkpoints for persistence to eliminate the IO overhead of a
 transactional data store.  On restart, bees will dedupe any data that
 was added to the filesystem since the last checkpoint.  Checkpoints
-occur every 15 minutes for scan progress, stored in `beescrawl.dat`.
+occur every 15 minutes for scan progress, stored in `beespoint.ini`.
 The hash table trickle-writes to disk at 128KiB/s to `beeshash.dat`,
 but will flush immediately if bees is terminated by SIGTERM.
 

diff --git a/docs/running.md b/docs/running.md
index 94d23f35afe9885a4a2d7d53ba46a2828838be92..1b5a94061aa36a1d1af1ad32371da817d0ccc7a3 100644 (file)
--- a/docs/running.md
+++ b/docs/running.md
@@ -51,7 +51,8 @@ There are some runtime configurable options using environment variables:
 
 * BEESHOME: Directory containing bees state files:
        * beeshash.dat  | persistent hash table.  Must be a multiple of 128KB, and must be created before bees starts.
-       * beescrawl.dat | state of SEARCH_V2 crawlers.  ASCII text.  bees will create this.
+       * beespoint.ini | state of extent and subvolume crawlers.  ASCII text in INI format.
+       * beescrawl.dat | state of old-version crawlers (legacy).  ASCII text.  Migrated to beespoint.ini on first run.
        * beesstats.txt | statistics and performance counters.  ASCII text.  bees will create this.
 * BEESSTATUS: Compatibility shortcut for
   `report.legacy.filename=$BEESSTATUS` and `report.legacy.active=yes`.

diff --git a/docs/state-file.md b/docs/state-file.md
index 3b62b2055e8aa9ed3f2b0edf009759af1bbd4589..c91556bdddab6a77bb04650589ead8fac4bc7b57 100644 (file)
--- a/docs/state-file.md
+++ b/docs/state-file.md
@@ -5,9 +5,13 @@ in the `$BEESHOME` directory.
 
 The file uses the same INI syntax as the bees [configuration
 files](config-format.md).  Each section records the scan position for one
-crawler.  On startup, bees reads `beespoint.ini`, resumes each crawler from
-its saved position, and appends new sections for any crawlers that are
-newly active in the current configuration.
+crawler.  If `state.persistent = yes` (the default) is configured, bees
+reads `beespoint.ini` on startup, resumes each crawler from its saved
+position, and appends new sections for any crawlers that are newly active
+in the current configuration.
+
+If `state.persistent = no` is configured, `beespoint.ini` is ignored on
+startup and never written to disk.
 
 ## File format
 
@@ -74,9 +78,10 @@ without losing each other's state.
 ## Migration from beescrawl.dat
 
 Older bees versions stored crawl state in `beescrawl.dat` in a
-whitespace-delimited key–value format.  On first run with a new bees
-version, if `beespoint.ini` is absent but `beescrawl.dat` is present, bees
-automatically migrates the old file:
+whitespace-delimited key–value format.  If `state.persistent = yes` is
+configured, on first run with a new bees version where `beespoint.ini` is
+absent but `beescrawl.dat` is present, bees automatically migrates the
+old file:
 
 1. Each entry in `beescrawl.dat` is matched to a `[scan.extent.NAME]`
    or `[scan.subvol.ID]` section.  The legacy "magic subvol" IDs