Group common options

doc/manual/generate-manpage.nix

@@ -38,31 +38,39 @@ let
     + (if def ? doc
        then def.doc + "\n\n"
        else "")
-    + (let s = showFlags def.flags; in
+    + (let s = showOptions def.flags; in
        if s != ""
-       then "# Flags\n\n${s}"
+       then "# Options\n\n${s}"
        else "")
   ;
 
   appendName = filename: name: (if filename == "nix" then "nix3" else filename) + "-" + name;
 
-  showFlags = flags:
+  showOptions = flags:
-    concatStrings
+    let
-      (map (longName:
+      categories = sort builtins.lessThan (unique (map (cmd: cmd.category) (attrValues flags)));
-        let flag = flags.${longName}; in
+    in
-        if flag.category or "" != "config"
+      concatStrings (map
-        then
+        (cat:
-          "  - `--${longName}`"
+          (if cat != ""
-          + (if flag ? shortName then " / `-${flag.shortName}`" else "")
+           then "**${cat}:**\n\n"
-          + (if flag ? labels then " " + (concatStringsSep " " (map (s: "*${s}*") flag.labels)) else "")
+           else "")
-          + "  \n"
+          + concatStrings
-          + "    " + flag.description + "\n\n"
+            (map (longName:
-        else "")
+              let
-        (attrNames flags));
+                flag = flags.${longName};
+              in
+                "  - `--${longName}`"
+                + (if flag ? shortName then " / `-${flag.shortName}`" else "")
+                + (if flag ? labels then " " + (concatStringsSep " " (map (s: "*${s}*") flag.labels)) else "")
+                + "  \n"
+                + "    " + flag.description + "\n\n"
+            ) (attrNames (filterAttrs (n: v: v.category == cat) flags))))
+        categories);
 
   showSynopsis =
     { command, args }:
-    "`${command}` [*flags*...] ${concatStringsSep " "
+    "`${command}` [*option*...] ${concatStringsSep " "
       (map (arg: "*${arg.label}*" + (if arg ? arity then "" else "...")) args)}\n\n";
 
   processCommand = { command, def, filename }:

src/libexpr/common-eval-args.cc

@@ -12,9 +12,12 @@ namespace nix {
 
 MixEvalArgs::MixEvalArgs()
 {
+    auto category = "Common evaluation options";
+
     addFlag({
         .longName = "arg",
         .description = "Pass the value *expr* as the argument *name* to Nix functions.",
+        .category = category,
         .labels = {"name", "expr"},
         .handler = {[&](std::string name, std::string expr) { autoArgs[name] = 'E' + expr; }}
     });
@@ -22,6 +25,7 @@ MixEvalArgs::MixEvalArgs()
     addFlag({
         .longName = "argstr",
         .description = "Pass the string *string* as the argument *name* to Nix functions.",
+        .category = category,
         .labels = {"name", "string"},
         .handler = {[&](std::string name, std::string s) { autoArgs[name] = 'S' + s; }},
     });
@@ -30,6 +34,7 @@ MixEvalArgs::MixEvalArgs()
         .longName = "include",
         .shortName = 'I',
         .description = "Add *path* to the list of locations used to look up `<...>` file names.",
+        .category = category,
         .labels = {"path"},
         .handler = {[&](std::string s) { searchPath.push_back(s); }}
     });
@@ -37,6 +42,7 @@ MixEvalArgs::MixEvalArgs()
     addFlag({
         .longName = "impure",
         .description = "Allow access to mutable paths and repositories.",
+        .category = category,
         .handler = {[&]() {
             evalSettings.pureEval = false;
         }},
@@ -45,6 +51,7 @@ MixEvalArgs::MixEvalArgs()
     addFlag({
         .longName = "override-flake",
         .description = "Override the flake registries, redirecting *original-ref* to *resolved-ref*.",
+        .category = category,
         .labels = {"original-ref", "resolved-ref"},
         .handler = {[&](std::string _from, std::string _to) {
             auto from = parseFlakeRef(_from, absPath("."));

src/libmain/common-args.cc

@@ -11,18 +11,21 @@ MixCommonArgs::MixCommonArgs(const string & programName)
         .longName = "verbose",
         .shortName = 'v',
         .description = "Increase the logging verbosity level.",
+        .category = loggingCategory,
         .handler = {[]() { verbosity = (Verbosity) (verbosity + 1); }},
     });
 
     addFlag({
         .longName = "quiet",
         .description = "Decrease the logging verbosity level.",
+        .category = loggingCategory,
         .handler = {[]() { verbosity = verbosity > lvlError ? (Verbosity) (verbosity - 1) : lvlError; }},
     });
 
     addFlag({
         .longName = "debug",
         .description = "Set the logging verbosity level to 'debug'.",
+        .category = loggingCategory,
         .handler = {[]() { verbosity = lvlDebug; }},
     });
 
@@ -52,6 +55,7 @@ MixCommonArgs::MixCommonArgs(const string & programName)
     addFlag({
         .longName = "log-format",
         .description = "Set the format of log output; one of `raw`, `internal-json`, `bar` or `bar-with-logs`.",
+        .category = loggingCategory,
         .labels = {"format"},
         .handler = {[](std::string format) { setLogFormat(format); }},
     });
@@ -66,7 +70,7 @@ MixCommonArgs::MixCommonArgs(const string & programName)
         }}
     });
 
-    std::string cat = "config";
+    std::string cat = "Options to override configuration settings";
     globalConfig.convertToArgs(*this, cat);
 
     // Backward compatibility hack: nix-env already had a --system flag.

src/libmain/common-args.hh

@@ -4,6 +4,9 @@
 
 namespace nix {
 
+//static constexpr auto commonArgsCategory = "Miscellaneous common options";
+static constexpr auto loggingCategory = "Logging-related options";
+
 struct MixCommonArgs : virtual Args
 {
     string programName;
@@ -16,7 +19,12 @@ struct MixDryRun : virtual Args
 
     MixDryRun()
     {
-        mkFlag(0, "dry-run", "Show what this command would do without doing it.", &dryRun);
+        addFlag({
+            .longName = "dry-run",
+            .description = "Show what this command would do without doing it.",
+            //.category = commonArgsCategory,
+            .handler = {&dryRun, true},
+        });
     }
 };
 
@@ -26,7 +34,12 @@ struct MixJSON : virtual Args
 
     MixJSON()
     {
-        mkFlag(0, "json", "Produce output in JSON format, suitable for consumption by another program.", &json);
+        addFlag({
+            .longName = "json",
+            .description = "Produce output in JSON format, suitable for consumption by another program.",
+            //.category = commonArgsCategory,
+            .handler = {&json, true},
+        });
     }
 };
 

src/libutil/args.cc

@@ -195,8 +195,7 @@ nlohmann::json Args::toJSON()
             j["shortName"] = std::string(1, flag->shortName);
         if (flag->description != "")
             j["description"] = flag->description;
-        if (flag->category != "")
+        j["category"] = flag->category;
-            j["category"] = flag->category;
         if (flag->handler.arity != ArityAny)
             j["arity"] = flag->handler.arity;
         if (!flag->labels.empty())

src/libutil/args.hh

@@ -91,7 +91,7 @@ protected:
         { }
     };
 
-    /* Flags. */
+    /* Options. */
     struct Flag
     {
         typedef std::shared_ptr<Flag> ptr;

src/nix/command.cc

@@ -61,6 +61,7 @@ StorePathsCommand::StorePathsCommand(bool recursive)
         addFlag({
             .longName = "no-recursive",
             .description = "Apply operation to specified paths only.",
+            .category = installablesCategory,
             .handler = {&this->recursive, false},
         });
     else
@@ -68,10 +69,16 @@ StorePathsCommand::StorePathsCommand(bool recursive)
             .longName = "recursive",
             .shortName = 'r',
             .description = "Apply operation to closure of the specified paths.",
+            .category = installablesCategory,
             .handler = {&this->recursive, true},
         });
 
-    mkFlag(0, "all", "Apply the operation to every store path.", &all);
+    addFlag({
+        .longName = "all",
+        .description = "Apply the operation to every store path.",
+        .category = installablesCategory,
+        .handler = {&all, true},
+    });
 }
 
 void StorePathsCommand::run(ref<Store> store)

src/nix/command.hh

@@ -23,6 +23,8 @@ static constexpr Command::Category catSecondary = 100;
 static constexpr Command::Category catUtility = 101;
 static constexpr Command::Category catNixInstallation = 102;
 
+static constexpr auto installablesCategory = "Options that change the interpretation of installables";
+
 struct NixMultiCommand : virtual MultiCommand, virtual Command
 {
     nlohmann::json toJSON() override;

src/nix/installables.cc

@@ -58,39 +58,47 @@ void completeFlakeInputPath(
 
 MixFlakeOptions::MixFlakeOptions()
 {
+    auto category = "Common flake-related options";
+
     addFlag({
         .longName = "recreate-lock-file",
         .description = "Recreate the flake's lock file from scratch.",
+        .category = category,
         .handler = {&lockFlags.recreateLockFile, true}
     });
 
     addFlag({
         .longName = "no-update-lock-file",
         .description = "Do not allow any updates to the flake's lock file.",
+        .category = category,
         .handler = {&lockFlags.updateLockFile, false}
     });
 
     addFlag({
         .longName = "no-write-lock-file",
         .description = "Do not write the flake's newly generated lock file.",
+        .category = category,
         .handler = {&lockFlags.writeLockFile, false}
     });
 
     addFlag({
         .longName = "no-registries",
         .description = "Don't allow lookups in the flake registries.",
+        .category = category,
         .handler = {&lockFlags.useRegistries, false}
     });
 
     addFlag({
         .longName = "commit-lock-file",
         .description = "Commit changes to the flake's lock file.",
+        .category = category,
         .handler = {&lockFlags.commitLockFile, true}
     });
 
     addFlag({
         .longName = "update-input",
         .description = "Update a specific flake input (ignoring its previous entry in the lock file).",
+        .category = category,
         .labels = {"input-path"},
         .handler = {[&](std::string s) {
             lockFlags.inputUpdates.insert(flake::parseInputPath(s));
@@ -104,6 +112,7 @@ MixFlakeOptions::MixFlakeOptions()
     addFlag({
         .longName = "override-input",
         .description = "Override a specific flake input (e.g. `dwarffs/nixpkgs`).",
+        .category = category,
         .labels = {"input-path", "flake-url"},
         .handler = {[&](std::string inputPath, std::string flakeRef) {
             lockFlags.inputOverrides.insert_or_assign(
@@ -115,6 +124,7 @@ MixFlakeOptions::MixFlakeOptions()
     addFlag({
         .longName = "inputs-from",
         .description = "Use the inputs of the specified flake as registry entries.",
+        .category = category,
         .labels = {"flake-url"},
         .handler = {[&](std::string flakeRef) {
             auto evalState = getEvalState();
@@ -144,6 +154,7 @@ SourceExprCommand::SourceExprCommand()
         .longName = "file",
         .shortName = 'f',
         .description = "Interpret installables as attribute paths relative to the Nix expression stored in *file*.",
+        .category = installablesCategory,
         .labels = {"file"},
         .handler = {&file},
         .completer = completePath
@@ -152,6 +163,7 @@ SourceExprCommand::SourceExprCommand()
     addFlag({
         .longName = "expr",
         .description = "Interpret installables as attribute paths relative to the Nix expression *expr*.",
+        .category = installablesCategory,
         .labels = {"expr"},
         .handler = {&expr}
     });
@@ -159,6 +171,7 @@ SourceExprCommand::SourceExprCommand()
     addFlag({
         .longName = "derivation",
         .description = "Operate on the store derivation rather than its outputs.",
+        .category = installablesCategory,
         .handler = {&operateOn, OperateOn::Derivation},
     });
 }

src/nix/main.cc

@@ -80,6 +80,7 @@ struct NixArgs : virtual MultiCommand, virtual MixCommonArgs
             .longName = "print-build-logs",
             .shortName = 'L',
             .description = "Print full build logs on standard error.",
+            .category = loggingCategory,
             .handler = {[&]() {setLogFormat(LogFormat::barWithLogs); }},
         });
 

src/nix/sigs.cc

@@ -16,7 +16,7 @@ struct CmdCopySigs : StorePathsCommand
         addFlag({
             .longName = "substituter",
             .shortName = 's',
-            .description = "Use signatures from specified store.",
+            .description = "Copy signatures from the specified store.",
             .labels = {"store-uri"},
             .handler = {[&](std::string s) { substituterUris.push_back(s); }},
         });
@@ -24,7 +24,7 @@ struct CmdCopySigs : StorePathsCommand
 
     std::string description() override
     {
-        return "copy path signatures from substituters (like binary caches)";
+        return "copy store path signatures from substituters";
     }
 
     void run(ref<Store> store, StorePaths storePaths) override
@@ -110,7 +110,7 @@ struct CmdSign : StorePathsCommand
 
     std::string description() override
     {
-        return "sign the specified paths";
+        return "sign store paths";
     }
 
     void run(ref<Store> store, StorePaths storePaths) override