]> git.hungrycats.org Git - bees/commitdiff
config: default resolve.commit-root to yes
authorZygo Blaxell <bees@furryterror.org>
Wed, 23 Sep 2026 03:49:23 +0000 (23:49 -0400)
committerZygo Blaxell <bees@furryterror.org>
Tue, 6 Oct 2026 05:51:40 +0000 (01:51 -0400)
The LOGICAL_INO_V2 commit-root flag is in the upstream kernel now, under
the same name, so the case for holding a tree mod log sequence across
every resolve by default is gone.  The kernel-side cost of a live-root
walk is paid by everything else running on the filesystem, not by bees,
and it is largest on exactly the heavily shared extents bees spends its
time resolving.

The staleness a commit-root answer carries is one transaction of other
writers' changes, which bees already tolerates as churn.  The one case
where a stale list did real damage -- an extent that had just served as
a dedupe source being re-planned as a destination from a list missing
the references that dedupe created -- was a planner defect, not a
property of the flag, and the earlier measurements that showed the
commit-root arm recovering less space were taken with that defect in
place.  Drop that claim from the docs rather than carry a number that
no longer describes the option.

Kernels without the flag still reject it once and bees falls back to
live-root walks, so the new default costs nothing where it cannot help.

Assisted-by: Claude-Code:claude-fable-5-1
docs/config-file.md
src/bees-config-v2.cc
src/bees-context.cc

index e3e7e5d931cb6298c5171c582db9b11f269557ee..20f4a6ff4a12223a5ba5272c2b64e278cdd00616 100644 (file)
@@ -797,20 +797,20 @@ The `[loop]` section controls the crawl loop lifecycle.  By default bees runs as
 The `[resolve]` section controls how bees maps a physical btrfs address back to the files that reference it, using the `LOGICAL_INO_V2` ioctl.
 
 * **`commit-root`**
-  Resolve references against the filesystem's commit roots instead of the live tree.  Default: `no`.
+  Resolve references against the filesystem's commit roots instead of the live tree.  Default: `yes`.
 
   With `no`, the kernel walks the running transaction's trees, so the reference list reflects the filesystem as it is at the moment of the call.  To keep that view consistent, the kernel holds a tree mod log sequence for the whole duration of the walk.  While any sequence is live, every node-level change anywhere on the filesystem is journalled into unreclaimable slab, and the journal is only trimmed below the oldest live sequence.  Walks of heavily-shared extents take the longest and therefore hold a sequence the longest, which is also when other work — balance, snapshot deletion — is most likely to be generating tree changes to journal.
 
   With `yes`, the answer comes from the last committed transaction, so no tree mod log sequence is held.  The cost is that the answer can be up to one transaction (roughly 30 seconds) stale: references created since the last commit are invisible.  bees is built to survive a stale answer — the kernel already falls back to the commit roots on its own whenever it cannot attach to a running transaction, the crawler only hands out extents from committed transactions, and references that vanish between the walk and the dedupe are treated as churn rather than errors — but surviving a stale answer is not the same as being unaffected by one.  A reference bees cannot see is a reference it does not dedupe, so the extent survives a dedupe that was supposed to free it, and the work is repeated on a later pass.
 
-  On a mixed real-data corpus, `yes` recovered less space and took longer to converge than `no`, despite each individual resolve being substantially cheaper.  The option exists mainly so the two can be compared on a single kernel, on a specific workload, without rebuilding.
+  The option exists so the two can be compared on a single kernel, on a specific workload, without rebuilding.
 
-  Kernels that do not implement commit-root resolution reject the request once with `EINVAL`; bees logs a warning and falls back to live-root walks for the rest of the run, so setting `yes` on such a kernel is harmless.
+  Kernels that do not implement commit-root resolution reject the request once with `EINVAL`; bees logs a warning and falls back to live-root walks for the rest of the run, so the default is harmless on such a kernel.
 
-  Example — resolve against the commit roots:
+  Example — resolve against the live tree instead:
   ```ini
   [resolve]
-  commit-root = yes
+  commit-root = no
   ```
 
 ## [scan.subvol] section
index e87ea7bff3e7b8dce3e66cd597450325c369bdd5..63c52f091e6044f4b71c9807903914b5c40970b1 100644 (file)
@@ -41,12 +41,12 @@ static const char bees_config_v2[] = R"--v2-config--(
 [resolve]
 
         # Resolve references against the commit roots instead of the live
-        # tree.  yes: answers come from the last committed transaction and
-        # may be up to one transaction stale, and the kernel holds no tree
-        # mod log sequence for the walk.  no (default): answers reflect the
-        # running transaction.  Ignored by kernels without the flag.
-        # See docs/config-file.md for the tradeoff.
-        commit-root = no
+        # tree.  yes (default): answers come from the last committed
+        # transaction and may be up to one transaction stale, and the
+        # kernel holds no tree mod log sequence for the walk.  no: answers
+        # reflect the running transaction.  Ignored by kernels without the
+        # flag.  See docs/config-file.md for the tradeoff.
+        commit-root = yes
 )--v2-config--";
 
 // Inherits from the schema that reproduces v0.11 behaviour; see the file
index 6a03eebde95d215696309ca94f8a2d693cbcb75c..4c3deae9bfdfc0e235dea258715b1552f8036dd6 100644 (file)
@@ -993,9 +993,8 @@ BeesContext::logical_ino(const uint64_t logical, const bool all_refs)
        // rather than errors -- but tolerating it is not the same as being
        // unaffected by it.
        //
-       // Measured on a mixed real-data corpus, asking for the commit root
-       // recovered less space and took longer to converge, so it is off by
-       // default.  The knob exists so the two can be compared on one kernel.
+       // On by default; the knob exists so the two can be compared on one
+       // kernel.
        //
        // Kernels that do not implement the flag reject it once with EINVAL,
        // after which libcrucible stops setting it.