]> git.hungrycats.org Git - bees/commitdiff
config: add --show-builtin-config and --show-config
authorZygo Blaxell <bees@furryterror.org>
Mon, 31 Aug 2026 00:42:14 +0000 (20:42 -0400)
committerZygo Blaxell <bees@furryterror.org>
Tue, 6 Oct 2026 05:51:40 +0000 (01:51 -0400)
There was no way to ask a bees build what configuration it would actually
use.  The built-in schema is only readable by reading the source of the
version files, and the merged view -- builtin under global under local
under argv, with ${VAR} expanded and one schema chained onto another --
exists only inside a running daemon.  An operator debugging a config
problem had to infer the answer from behaviour.

Add two options that print it.  --show-builtin-config VERSION resolves a
schema version and writes what it resolves to; --show-config ROOT_PATH
loads configuration for a real filesystem and writes the merged result.
Both write to stdout and exit without starting deduplication.

The builtin form reads nothing at all: no filesystem, no config file, no
environment.  That is what makes it usable offline, and it is why
--config and --option are now recorded during option parsing and applied
afterwards rather than acted on as getopt_long reaches them.  Option
order belongs to the caller, so applied inline, --config f.conf
--show-builtin-config 2 would have read f.conf before the early exit ran,
and the command would be lying about what it loaded.

The output is INI, and carries the highest-priority non-blank comment for
each key along with the value, so what it prints is also documentation
for what it prints.  A builtin version is dumped through the same builder
as the merged view, because with inheritance in play the text a version
registered is no longer the same thing as what that version resolves to.

Assisted-by: Claude-Code:claude-opus-5
Signed-off-by: Zygo Blaxell <bees@furryterror.org>
docs/options.md
src/bees-config.cc
src/bees-config.h
src/bees-usage.cc
src/bees.cc

index 48c18a344aca6063824676a21c6be44a741fee7c..a9a083597910d03b7031736e131232c41f7bfb4c 100644 (file)
@@ -106,6 +106,31 @@ space used--until the read-only snapshots are deleted.
  fails dedupe with `EAGAIN` when a send is in progress.  bees handles
  `EAGAIN` automatically via a retry loop.
 
+## Configuration debug options
+
+* `--show-builtin-config VERSION`
+
+  Write the built-in configuration for `VERSION` to standard output and exit.
+  `VERSION` may be a numeric config version accepted by this bees build, the
+  alias `CURRENT` or `STABLE`, or a release alias such as `v0.11`.
+
+  This command does not load a filesystem, global config file, local config
+  file, environment-derived paths, or `--config` / `--option` input.  It is
+  intended for offline inspection of the compiled-in defaults.
+
+* `--show-config ROOT_PATH`
+
+  Load configuration for `ROOT_PATH`, write the merged configuration to
+  standard output, and exit without running deduplication.  `ROOT_PATH` must
+  be the root of a btrfs filesystem tree (subvol id 5), the same as a normal
+  bees run.
+
+  The output is a self-documenting INI snapshot: each key is written with
+  the highest-priority non-blank documentation comment found anywhere in
+  the fallback chain, so the dumped file shows both the effective value and
+  the builtin documentation for each key.  Keys are written in
+  alphabetical order within each section.
+
 ## Logging options
 
 * `--timestamps` or `-t`
index fa94d84f6012246ad204a980cf7e1a92219fdc68..4b0d6202888eed2afe33c055cf722b904a9fe85d 100644 (file)
@@ -12,6 +12,7 @@
 #include <cmath>
 #include <sstream>
 #include <sys/statfs.h>
+#include <vector>
 
 unique_ptr<BeesConfig::DefaultMap> BeesConfig::s_defaults;
 unique_ptr<BeesConfig::PreviousMap> BeesConfig::s_previous;
@@ -154,6 +155,9 @@ void
 BeesConfig::set_version_defaults(Innie &target, const string &version)
 {
        BEESTRACE("resolving builtin config version '" << version << "'");
+       // Resolve through the alias table rather than through entries in
+       // s_defaults: this runs for --show-builtin-config, which never builds a
+       // BeesConfig because it has no filesystem to build one against.
        const auto resolved = resolve_version(version);
        if (!s_defaults || !s_defaults->count(resolved)) {
                THROW_ERROR(invalid_argument,
@@ -382,6 +386,84 @@ BeesConfig::sections(const string &prefix) const
        return m_innie.sections(prefix);
 }
 
+const Innie &
+BeesConfig::innie() const
+{
+       return m_innie;
+}
+
+/// Build a fresh Innie that captures the merged value and best comment for
+/// every key visible through @p merged.  Used by bees_show_config to produce
+/// a self-documenting INI snapshot.
+///
+/// Top-level section names come from Innie::root_sections(), which walks
+/// the fallback chain and returns every immediate child of the root node
+/// (including namespace-only nodes).  This keeps the dump schema-agnostic:
+/// user-defined top-level sections are captured along with builtin names.
+///
+/// For each (section, key) pair, the merged value and the highest-priority
+/// non-blank comment (from get_comment) are written into @p out.  Section-
+/// header comments are also copied across so the dump preserves the prose
+/// that documents each [section] in the source config.
+void
+bees_build_dump_innie(const Innie &merged, Innie &out)
+{
+       BEESTRACE("bees_build_dump_innie");
+
+       // Copy keys, key-level comments, and the section-header comment for one
+       // concrete section (no recursion).  sections() below enumerates every
+       // content-bearing descendant as a compound relative name, so a single
+       // call from each top-level section covers the full sub-hierarchy.
+       const auto dump_one_section = [&](const string &section) {
+               BEESTRACE("dumping section " << section);
+               const string section_comment = merged.get_section_comment(section);
+               if (!section_comment.empty()) {
+                       out.set_section_comment(section, section_comment);
+               }
+               for (const auto &key : merged.keys(section)) {
+                       const string sk = section + "." + key;
+                       out.set(sk, merged.get(sk));
+                       const string comment = merged.get_comment(sk);
+                       if (!comment.empty()) {
+                               out.set_comment(sk, comment);
+                       }
+               }
+       };
+
+       for (const auto &top : merged.root_sections()) {
+               dump_one_section(top);
+               // Content-bearing children are returned as compound relative
+               // names (e.g. "extent.128K" under "scan").
+               for (const auto &child : merged.sections(top)) {
+                       dump_one_section(top + "." + child);
+               }
+       }
+}
+
+void
+bees_show_builtin_config(const string &version)
+{
+       // What a version resolves to is not the same as the text it registered
+       // once inheritance is involved, and Innie::write() dumps a single rep.
+       // Build the resolved view and dump it the way --show-config does.
+       Innie resolved;
+       BeesConfig::set_version_defaults(resolved, version);
+       Innie out;
+       out.set_origin("builtin version " + version);
+       bees_build_dump_innie(resolved, out);
+       out.write(cout);
+}
+
+void
+bees_show_config(const BeesConfig &cfg)
+{
+       BEESTRACE("dumping merged config to stdout");
+       Innie out;
+       out.set_origin("merged view");
+       bees_build_dump_innie(cfg.innie(), out);
+       out.write(cout);
+}
+
 bool
 bees_parse_bool(const string& str)
 {
index d50a064373c6956e09ba28b7ad10a0fde04921fc..3aa61d6a844aad4026dc264b082fc39b082cfd02 100644 (file)
@@ -183,6 +183,10 @@ public:
        /// Return the set of section-name suffixes immediately under @p prefix.
        /// E.g. sections("scan.extent") returns {"128K", "512K", ...}.
        set<string> sections(const string &prefix) const;
+       /// Return the merged Innie for direct key/section access.  Used by the
+       /// config dump helpers below, which walk every visible section rather
+       /// than looking up known keys through the typed get() template.
+       const Innie &innie() const;
 
        /**
         * Look up @p section_and_key (e.g. @c "scanner/threads") in the merged
@@ -206,9 +210,27 @@ public:
                        throw;
                }
        }
-
 };
 
+/// @name Configuration dump helpers
+/// @{
+
+/// Build a merged INI snapshot into @p out.  For each (section, key) visible
+/// in @p merged, write the merged value and the highest-priority non-blank
+/// comment into @p out.  Exposed for unit testing; production code calls
+/// bees_show_config() which wraps this.
+void bees_build_dump_innie(const Innie &merged, Innie &out);
+
+/// Write the merged config to stdout.
+void bees_show_config(const BeesConfig &cfg);
+
+/// Write the resolved defaults for a builtin config version to stdout, without
+/// loading filesystem or user configuration.  Accepts any name in
+/// version_aliases(), including release aliases such as "v0.11".
+void bees_show_builtin_config(const string &version);
+
+/// @}
+
 /// @name Configuration value parsing helpers
 /// @{
 
index 6a7f4a96d713fef0257810f9c996007b4ab8605b..0a1e3652fd2bb9499cc0e264605dad8fdd2289ea 100644 (file)
@@ -17,6 +17,13 @@ Options:
         --config FILE     Read configuration options from FILE
     -o, --option          Set one configuration option in `key=value` format
 
+Configuration debug options:
+        --show-builtin-config VERSION
+                          Write builtin config VERSION to stdout and exit.
+        --show-config ROOT_PATH
+                          Write the merged config for ROOT_PATH to stdout.
+                          See `docs/options.md` for details.
+
 Load management options:
     -c, --thread-count    Exact worker thread count (overrides factor)
                           [thread.thread-max]
index c044adff4f6c95ebc441c0b3635534b66f87313a..c5bf7313dbfdffdd2383e8727630699db8c84fd3 100644 (file)
@@ -170,6 +170,26 @@ bees_main(int argc, char *argv[])
 
        THROW_CHECK1(invalid_argument, argc, argc >= 0);
 
+       string show_builtin_config_version;
+       bool show_merged_config = false;
+       string show_config_root_path;
+       int show_config_option_count = 0;
+
+       // --config and --option are recorded here and applied further down,
+       // rather than acted on as getopt_long reaches them.  --show-builtin-config
+       // promises to read nothing, and option order is the caller's to choose:
+       // applied inline, `--config f.conf --show-builtin-config 2` would have
+       // already read f.conf by the time the early exit ran.
+       struct ConfigInput {
+               enum class Type {
+                       File,
+                       Option,
+               };
+               Type type;
+               string text;
+       };
+       vector<ConfigInput> config_inputs;
+
        // Construct an Innie
        Innie bconfig;
 
@@ -213,15 +233,26 @@ bees_main(int argc, char *argv[])
                },
                { .name = "config", .has_arg = required_argument,
                        .fn = [&]() {
-                               ifstream ifs(optarg);
-                               if (!ifs.is_open()) {
-                                       THROW_ERRNO("cannot open config file '" << optarg << "' for reading");
-                               }
-                               bconfig.read(ifs);
+                               config_inputs.push_back({ ConfigInput::Type::File, optarg });
                        }
                },
                { .name = "option", .has_arg = required_argument, .val = 'o',
-                       .fn = [&]() { bconfig.read(optarg); }
+                       .fn = [&]() {
+                               config_inputs.push_back({ ConfigInput::Type::Option, optarg });
+                       }
+               },
+               { .name = "show-builtin-config", .has_arg = required_argument,
+                       .fn = [&]() {
+                               ++show_config_option_count;
+                               show_builtin_config_version = optarg;
+                       }
+               },
+               { .name = "show-config", .has_arg = required_argument,
+                       .fn = [&]() {
+                               ++show_config_option_count;
+                               show_merged_config = true;
+                               show_config_root_path = optarg;
+                       }
                },
                { .name = "help", .has_arg = no_argument, .val = 'h',
                        .fn = [&]() {
@@ -311,11 +342,46 @@ bees_main(int argc, char *argv[])
 
        // Log verbosity has been set, so now we can start setting things up
 
-       if (optind + 1 != argc) {
+       const bool show_builtin_config = !show_builtin_config_version.empty();
+       if (show_config_option_count > 1) {
+               BEESLOGERR("Only one --show-*-config option may be used");
+               return EXIT_FAILURE;
+       }
+       if (show_builtin_config) {
+               if (optind != argc) {
+                       BEESLOGERR("--show-builtin-config does not take a filesystem path");
+                       return EXIT_FAILURE;
+               }
+               bees_show_builtin_config(show_builtin_config_version);
+               return EXIT_SUCCESS;
+       }
+
+       string root_path;
+       if (show_merged_config) {
+               if (optind != argc) {
+                       BEESLOGERR("--show-config takes ROOT_PATH as its option argument");
+                       return EXIT_FAILURE;
+               }
+               root_path = show_config_root_path;
+       } else if (optind + 1 == argc) {
+               root_path = argv[optind++];
+       } else {
                BEESLOGERR("Exactly one filesystem path required");
                return EXIT_FAILURE;
        }
 
+       for (const auto &input : config_inputs) {
+               if (input.type == ConfigInput::Type::File) {
+                       ifstream ifs(input.text);
+                       if (!ifs.is_open()) {
+                               THROW_ERRNO("cannot open config file '" << input.text << "' for reading");
+                       }
+                       bconfig.read(ifs);
+               } else {
+                       bconfig.read(input.text);
+               }
+       }
+
        const char *base_dir = getenv("BEESHOME");
        if (base_dir) {
                bconfig.set("path.home", base_dir);
@@ -350,12 +416,18 @@ bees_main(int argc, char *argv[])
        BEESTRACE("context constructed");
 
        // Set root path and open root FD
-       string root_path = argv[optind++];
        bc->set_root_path(root_path);
 
        // Set configuration
        bc->set_config(bconfig);
 
+       // If --show-config was requested, write the merged view and exit.
+       if (show_merged_config) {
+               BEESTRACE("showing config and exiting");
+               bees_show_config(bc->get_config());
+               return EXIT_SUCCESS;
+       }
+
        // Start each scanner independently based on config.
        // --scan-mode only sets the config keys; it does not directly select the scanner.
        // Both subvol and extent scanners may run simultaneously if both are enabled.