Document default options files for commands

35 files changed, 588 insertions, 8 deletions

diff --git a/bpkg/.gitignore b/bpkg/.gitignore
index e2eadc4..4a212df 100644
--- a/bpkg/.gitignore
+++ b/bpkg/.gitignore
@@ -5,6 +5,7 @@ bpkg
 repository-signing.?xx
 repository-types.?xx
 argument-grouping.?xx
+default-options-files.?xx
 version.hxx
 
 # Testscript output directory (can be symlink).
diff --git a/bpkg/bpkg.cli b/bpkg/bpkg.cli
index 573189c..37e25be 100644
--- a/bpkg/bpkg.cli
+++ b/bpkg/bpkg.cli
@@ -286,6 +286,11 @@ namespace bpkg
       "\l{bpkg-common-options(1)} \- details on common options"
     }
 
+    bool default-options-files
+    {
+      "\l{bpkg-default-options-files(1)} \- specifying default options"
+    }
+
     bool repository-types
     {
       "\l{bpkg-repository-types(1)} \- repository types, structure, and URLs"
diff --git a/bpkg/buildfile b/bpkg/buildfile
index 5275437..ca3cdb9 100644
--- a/bpkg/buildfile
+++ b/bpkg/buildfile
@@ -42,7 +42,10 @@ rep-info-options           \
 rep-list-options           \
 rep-remove-options
 
-help_topics = repository-signing repository-types argument-grouping
+help_topics = repository-signing    \
+              repository-types      \
+              argument-grouping     \
+              default-options-files
 
 ./: exe{bpkg}: {hxx ixx txx cxx}{+bpkg} libue{bpkg}
 
@@ -146,9 +149,10 @@ if $cli.configured
 
   # Help topics.
   #
-  cli.cxx{repository-signing}: cli{repository-signing}
-  cli.cxx{repository-types}:   cli{repository-types}
-  cli.cxx{argument-grouping}:  cli{argument-grouping}
+  cli.cxx{repository-signing}:    cli{repository-signing}
+  cli.cxx{repository-types}:      cli{repository-types}
+  cli.cxx{argument-grouping}:     cli{argument-grouping}
+  cli.cxx{default-options-files}: cli{default-options-files}
 
   # Option length must be the same to get commands/topics/options aligned.
   #
@@ -170,7 +174,8 @@ bpkg::pkg_build_pkg_options=exclude-base --generate-modifier
 
   # Avoid generating CLI runtime and empty inline file for help topics.
   #
-  cli.cxx{repository-signing repository-types argument-grouping}: \
+  cli.cxx{repository-signing repository-types argument-grouping \
+          default-options-files}:                               \
     cli.options += --suppress-cli --suppress-inline
 
   # Include the generated cli files into the distribution and don't remove
diff --git a/bpkg/cfg-create.cli b/bpkg/cfg-create.cli
index 571c614..2bda017 100644
--- a/bpkg/cfg-create.cli
+++ b/bpkg/cfg-create.cli
@@ -79,4 +79,27 @@ namespace bpkg
        configuration directory explicitly with \cb{--directory|-d}."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{cfg-create} command the search start directory
+   is the parent directory of the new configuration. The following options
+   files are searched for in each directory and, if found, loaded in the
+   order listed:
+
+   \
+   bpkg.options
+   bpkg-cfg-create.options
+   \
+
+   The following \cb{cfg-create} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   --wipe
+   \
+  "
 }
diff --git a/bpkg/cfg-create.cxx b/bpkg/cfg-create.cxx
index affc0b0..4563374 100644
--- a/bpkg/cfg-create.cxx
+++ b/bpkg/cfg-create.cxx
@@ -175,6 +175,8 @@ namespace bpkg
   default_options_files
   options_files (const char*, const cfg_create_options& o, const strings&)
   {
+    // NOTE: remember to update the documentation if changing anything here.
+
     // bpkg.options
     // bpkg-cfg-create.options
 
@@ -198,6 +200,8 @@ namespace bpkg
   merge_options (const default_options<cfg_create_options>& defs,
                  const cfg_create_options& cmd)
   {
+    // NOTE: remember to update the documentation if changing anything here.
+
     return merge_default_options (
       defs,
       cmd,
diff --git a/bpkg/default-options-files.cli b/bpkg/default-options-files.cli
new file mode 100644
index 0000000..9b4af38
--- /dev/null
+++ b/bpkg/default-options-files.cli
@@ -0,0 +1,73 @@
+// file      : bpkg/default-options-files.cli
+// copyright : Copyright (c) 2014-2019 Code Synthesis Ltd
+// license   : MIT; see accompanying LICENSE file
+
+include <bpkg/common-options.hxx>;
+
+"\section=1"
+"\name=bpkg-default-options-files"
+"\summary=specifying default options"
+
+{
+  "<command> <mode-options>",
+
+  "
+  \h|SYNOPSIS|
+
+  \c{\b{bpkg} <command> [<mode-options>] ...}
+
+  \h|DESCRIPTION|
+
+  Instead of having a separate config file format for tool configuration, the
+  \cb{build2} toolchain uses \i{default options files} which contain the same
+  options as what can be specified on the command line. The default options
+  files are like options files that one can specify with \cb{--options-file}
+  (\l{bpkg-common-options(1)}) except that they are loaded by default.
+
+  The default options files are searched for in the \cb{.build2/} and
+  \cb{.build2/local/} subdirectories of each outer directory beginning from
+  the \i{start directory} and until reaching either the home directory or the
+  filesystem root directory (both excluding). Then in the \cb{.build2/}
+  subdirectory of the home directory and finally in the system directory (for
+  example, \cb{/etc/build2/}) if configured.
+
+  Once the search is complete, the files are loaded in the reverse order, that
+  is, beginning from the system directory (if any), followed by the home
+  directory, ending with the start directory, and finishing off with the
+  options specified on the command line.  In other words, the files are loaded
+  from the more generic to the more specific with the command line options
+  having the ability to override any values specified in the default options
+  files.
+
+  The start directory, the names of the default options files, and in which
+  order they are loaded within each directory are determined by the <command>
+  and potentially its <mode-options>. See each command's DEFAULT OPTIONS FILES
+  section for details.
+
+  If a default options file contains \cb{--no-default-options}, then the
+  search is stopped at the directory containing this file and no outer files
+  are loaded. If this option is specified on the command line, then none of
+  the default options files are searched for or loaded.
+
+  An additional directory containing default options files can be specified
+  with \cb{--default-options}. If such a directory is a subdirectory of the
+  start directory or is between the start directory and the end of the outer
+  search, then its configuration files are loaded at the corresponding point
+  in the directory hierarchy. Otherwise, they are loaded after the home
+  directory.
+
+  The presence of the \cb{.git} filesystem entry causes the default options
+  files in this directory and any of its subdirectories to be considered
+  remote. Depending on the command, some security-sensitive options may be
+  disallowed or trigger a prompt when specified in remote options files (in
+  the current implementation this is the case even for files from the
+  \cb{.build2/local/} subdirectory since the mere location is not a sufficient
+  ground to definitively conclude that the file is not remote; to be sure we
+  would need to query the version control system). Note that additional
+  default options files specified with \cb{--default-options} are never
+  considered remote.
+
+  The order in which default options files are loaded is traced at the
+  verbosity level 3 (\cb{-V} option) or higher.
+  "
+}
diff --git a/bpkg/help.cli b/bpkg/help.cli
index f5fda42..4c87146 100644
--- a/bpkg/help.cli
+++ b/bpkg/help.cli
@@ -27,4 +27,18 @@ namespace bpkg
   {
     //"\h|HELP OPTIONS|"
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{help} command the following options files are
+   searched for only in the predefined directories (home, system, etc) and, if
+   found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-help.options
+   \
+  "
 }
diff --git a/bpkg/help.cxx b/bpkg/help.cxx
index 3946a5f..4b655f1 100644
--- a/bpkg/help.cxx
+++ b/bpkg/help.cxx
@@ -14,6 +14,7 @@
 #include <bpkg/repository-signing.hxx>
 #include <bpkg/repository-types.hxx>
 #include <bpkg/argument-grouping.hxx>
+#include <bpkg/default-options-files.hxx>
 
 using namespace std;
 using namespace butl;
@@ -38,6 +39,8 @@ namespace bpkg
         usage = &print_bpkg_repository_types_usage;
       else if (t == "argument-grouping")
         usage = &print_bpkg_argument_grouping_usage;
+      else if (t == "default-options-files")
+        usage = &print_bpkg_default_options_files_usage;
       else
         fail << "unknown bpkg command/help topic '" << t << "'" <<
           info << "run 'bpkg help' for more information";
diff --git a/bpkg/pkg-build.cli b/bpkg/pkg-build.cli
index 0ac8dcb..d4a8841 100644
--- a/bpkg/pkg-build.cli
+++ b/bpkg/pkg-build.cli
@@ -296,4 +296,25 @@ namespace bpkg
        option in \l{bpkg-rep-fetch(1)} for details."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{pkg-build} command the search start
+   directory is the configuration directory. The following options files are
+   searched for in each directory and, if found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-pkg-build.options
+   \
+
+   The following \cb{pkg-build} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bpkg/pkg-checkout.cli b/bpkg/pkg-checkout.cli
index 869aef0..509d88b 100644
--- a/bpkg/pkg-checkout.cli
+++ b/bpkg/pkg-checkout.cli
@@ -38,4 +38,25 @@ namespace bpkg
        unpacked."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{pkg-checkout} command the search start directory
+   is the configuration directory. The following options files are searched
+   for in each directory and, if found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-pkg-checkout.options
+   \
+
+   The following \cb{pkg-checkout} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bpkg/pkg-clean.cli b/bpkg/pkg-clean.cli
index 78802af..4cdd0a2 100644
--- a/bpkg/pkg-clean.cli
+++ b/bpkg/pkg-clean.cli
@@ -42,4 +42,25 @@ namespace bpkg
       "Clean all held packages."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{pkg-clean} command the search start directory
+   is the configuration directory. The following options files are searched
+   for in each directory and, if found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-pkg-clean.options
+   \
+
+   The following \cb{pkg-clean} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bpkg/pkg-configure.cli b/bpkg/pkg-configure.cli
index 0f51aa0..6908018 100644
--- a/bpkg/pkg-configure.cli
+++ b/bpkg/pkg-configure.cli
@@ -38,4 +38,25 @@ namespace bpkg
   {
     "\h|PKG-CONFIGURE OPTIONS|"
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{pkg-configure} command the search start
+   directory is the configuration directory. The following options files are
+   searched for in each directory and, if found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-pkg-configure.options
+   \
+
+   The following \cb{pkg-configure} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bpkg/pkg-disfigure.cli b/bpkg/pkg-disfigure.cli
index db3b1d4..a97b68e 100644
--- a/bpkg/pkg-disfigure.cli
+++ b/bpkg/pkg-disfigure.cli
@@ -38,4 +38,25 @@ namespace bpkg
       "Don't clean the package's output directory."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{pkg-disfigure} command the search start
+   directory is the configuration directory. The following options files are
+   searched for in each directory and, if found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-pkg-disfigure.options
+   \
+
+   The following \cb{pkg-disfigure} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bpkg/pkg-drop.cli b/bpkg/pkg-drop.cli
index 7002d57..298cafc 100644
--- a/bpkg/pkg-drop.cli
+++ b/bpkg/pkg-drop.cli
@@ -83,4 +83,25 @@ namespace bpkg
        <header> line (unless it is empty)."
     };
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{pkg-drop} command the search start
+   directory is the configuration directory. The following options files are
+   searched for in each directory and, if found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-pkg-drop.options
+   \
+
+   The following \cb{pkg-drop} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bpkg/pkg-fetch.cli b/bpkg/pkg-fetch.cli
index 1986627..8056c35 100644
--- a/bpkg/pkg-fetch.cli
+++ b/bpkg/pkg-fetch.cli
@@ -58,4 +58,26 @@ namespace bpkg
       "Remove the existing package archive when the package is purged."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{pkg-fetch} command the search start
+   directory is the configuration directory. The following options files are
+   searched for in each directory and, if found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-pkg-fetch.options
+   \
+
+   The following \cb{pkg-fetch} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   --purge|-p
+   \
+  "
 }
diff --git a/bpkg/pkg-fetch.cxx b/bpkg/pkg-fetch.cxx
index b86ac85..0c880ac 100644
--- a/bpkg/pkg-fetch.cxx
+++ b/bpkg/pkg-fetch.cxx
@@ -351,6 +351,8 @@ namespace bpkg
   merge_options (const default_options<pkg_fetch_options>& defs,
                  const pkg_fetch_options& cmd)
   {
+    // NOTE: remember to update the documentation if changing anything here.
+
     return merge_default_options (
       defs,
       cmd,
diff --git a/bpkg/pkg-install.cli b/bpkg/pkg-install.cli
index 9caf48b..4f54a8f 100644
--- a/bpkg/pkg-install.cli
+++ b/bpkg/pkg-install.cli
@@ -65,4 +65,25 @@ namespace bpkg
       "Also install all dependencies, recursively."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{pkg-install} command the search start
+   directory is the configuration directory. The following options files are
+   searched for in each directory and, if found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-pkg-install.options
+   \
+
+   The following \cb{pkg-install} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bpkg/pkg-purge.cli b/bpkg/pkg-purge.cli
index f4ae2eb..7128d0e 100644
--- a/bpkg/pkg-purge.cli
+++ b/bpkg/pkg-purge.cli
@@ -46,4 +46,25 @@ namespace bpkg
        package from the configuration."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{pkg-purge} command the search start
+   directory is the configuration directory. The following options files are
+   searched for in each directory and, if found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-pkg-purge.options
+   \
+
+   The following \cb{pkg-purge} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bpkg/pkg-status.cli b/bpkg/pkg-status.cli
index 999e3c3..6d8dad8 100644
--- a/bpkg/pkg-status.cli
+++ b/bpkg/pkg-status.cli
@@ -194,4 +194,25 @@ namespace bpkg
       "Don't print the version hold status."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{pkg-status} command the search start
+   directory is the configuration directory. The following options files are
+   searched for in each directory and, if found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-pkg-status.options
+   \
+
+   The following \cb{pkg-status} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bpkg/pkg-test.cli b/bpkg/pkg-test.cli
index afa05aa..6ccb8c1 100644
--- a/bpkg/pkg-test.cli
+++ b/bpkg/pkg-test.cli
@@ -55,4 +55,25 @@ namespace bpkg
       "Also test all dependencies, recursively."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{pkg-test} command the search start
+   directory is the configuration directory. The following options files are
+   searched for in each directory and, if found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-pkg-test.options
+   \
+
+   The following \cb{pkg-test} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bpkg/pkg-uninstall.cli b/bpkg/pkg-uninstall.cli
index 6c17866..d36a8e8 100644
--- a/bpkg/pkg-uninstall.cli
+++ b/bpkg/pkg-uninstall.cli
@@ -56,4 +56,25 @@ namespace bpkg
       "Also uninstall all dependencies, recursively."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{pkg-uninstall} command the search start
+   directory is the configuration directory. The following options files are
+   searched for in each directory and, if found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-pkg-uninstall.options
+   \
+
+   The following \cb{pkg-uninstall} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bpkg/pkg-unpack.cli b/bpkg/pkg-unpack.cli
index c2ec3ea..bafab7e 100644
--- a/bpkg/pkg-unpack.cli
+++ b/bpkg/pkg-unpack.cli
@@ -74,4 +74,26 @@ namespace bpkg
        fetched. Can only be specified with an external package."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{pkg-unpack} command the search start
+   directory is the configuration directory. The following options files are
+   searched for in each directory and, if found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-pkg-unpack.options
+   \
+
+   The following \cb{pkg-unpack} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   --purge|-p
+   \
+  "
 }
diff --git a/bpkg/pkg-unpack.cxx b/bpkg/pkg-unpack.cxx
index 801496d..7727535 100644
--- a/bpkg/pkg-unpack.cxx
+++ b/bpkg/pkg-unpack.cxx
@@ -433,6 +433,8 @@ namespace bpkg
   merge_options (const default_options<pkg_unpack_options>& defs,
                  const pkg_unpack_options& cmd)
   {
+    // NOTE: remember to update the documentation if changing anything here.
+
     return merge_default_options (
       defs,
       cmd,
diff --git a/bpkg/pkg-update.cli b/bpkg/pkg-update.cli
index 9eb98b8..57e46ad 100644
--- a/bpkg/pkg-update.cli
+++ b/bpkg/pkg-update.cli
@@ -52,4 +52,25 @@ namespace bpkg
        \cb{install} or \cb{test}."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{pkg-update} command the search start
+   directory is the configuration directory. The following options files are
+   searched for in each directory and, if found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-pkg-update.options
+   \
+
+   The following \cb{pkg-update} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bpkg/pkg-verify.cli b/bpkg/pkg-verify.cli
index 0546695..49714a0 100644
--- a/bpkg/pkg-verify.cli
+++ b/bpkg/pkg-verify.cli
@@ -59,4 +59,18 @@ namespace bpkg
        files and the package dependency constraints are completed."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{pkg-verify} command the following options files
+   are searched for in the predefined directories (system, etc) and, if found,
+   loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-pkg-verify.options
+   \
+  "
 }
diff --git a/bpkg/rep-add.cli b/bpkg/rep-add.cli
index 3bfd537..f9a91fa 100644
--- a/bpkg/rep-add.cli
+++ b/bpkg/rep-add.cli
@@ -57,4 +57,25 @@ namespace bpkg
        and \cb{git}."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{rep-add} command the search start
+   directory is the configuration directory. The following options files are
+   searched for in each directory and, if found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-rep-add.options
+   \
+
+   The following \cb{rep-add} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bpkg/rep-create.cli b/bpkg/rep-create.cli
index 006cf56..557d941 100644
--- a/bpkg/rep-create.cli
+++ b/bpkg/rep-create.cli
@@ -45,4 +45,25 @@ namespace bpkg
        \cb{openssl} cryptographic engine is used."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{rep-create} command the search start
+   directory is the repository directory. The following options files are
+   searched for in each directory and, if found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-rep-create.options
+   \
+
+   The following \cb{rep-create} command options cannot be specified in the
+   remote default options files:
+
+   \
+   --key
+   \
+  "
 }
diff --git a/bpkg/rep-create.cxx b/bpkg/rep-create.cxx
index 98bf7f8..12bc6e5 100644
--- a/bpkg/rep-create.cxx
+++ b/bpkg/rep-create.cxx
@@ -260,6 +260,8 @@ namespace bpkg
   default_options_files
   options_files (const char*, const rep_create_options&, const strings& args)
   {
+    // NOTE: remember to update the documentation if changing anything here.
+
     // bpkg.options
     // bpkg-rep-create.options
 
@@ -286,6 +288,8 @@ namespace bpkg
   merge_options (const default_options<rep_create_options>& defs,
                  const rep_create_options& cmd)
   {
+    // NOTE: remember to update the documentation if changing anything here.
+
     return merge_default_options (
       defs,
       cmd,
diff --git a/bpkg/rep-fetch.cli b/bpkg/rep-fetch.cli
index 6c564e7..c9ac510 100644
--- a/bpkg/rep-fetch.cli
+++ b/bpkg/rep-fetch.cli
@@ -47,4 +47,25 @@ namespace bpkg
        prerequisites has changed."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{rep-fetch} command the search start
+   directory is the configuration directory. The following options files are
+   searched for in each directory and, if found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-rep-fetch.options
+   \
+
+   The following \cb{rep-fetch} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bpkg/rep-info.cli b/bpkg/rep-info.cli
index 916209f..9cecd3d 100644
--- a/bpkg/rep-info.cli
+++ b/bpkg/rep-info.cli
@@ -128,4 +128,27 @@ namespace bpkg
       "Use configuration in <dir> for the trusted certificate database."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. If the \cb{rep-info} command uses an existing \c{bpkg}
+   configuration, then the start directory is the configuration directory.
+   Otherwise, only the predefined directories (home, system, etc) are
+   searched. The following options files are searched for in each directory
+   and, if found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-rep-info.options
+   \
+
+   The following \cb{rep-info} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bpkg/rep-info.cxx b/bpkg/rep-info.cxx
index 086a142..b90ace8 100644
--- a/bpkg/rep-info.cxx
+++ b/bpkg/rep-info.cxx
@@ -378,6 +378,8 @@ namespace bpkg
   default_options_files
   options_files (const char*, const rep_info_options& o, const strings&)
   {
+    // NOTE: remember to update the documentation if changing anything here.
+
     // bpkg.options
     // bpkg-rep-info.options
 
@@ -411,6 +413,8 @@ namespace bpkg
   merge_options (const default_options<rep_info_options>& defs,
                  const rep_info_options& cmd)
   {
+    // NOTE: remember to update the documentation if changing anything here.
+
     return merge_default_options (
       defs,
       cmd,
diff --git a/bpkg/rep-list.cli b/bpkg/rep-list.cli
index 44241fd..59d6f09 100644
--- a/bpkg/rep-list.cli
+++ b/bpkg/rep-list.cli
@@ -43,4 +43,25 @@ namespace bpkg
       "List prerequisite repositories."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{rep-list} command the search start
+   directory is the configuration directory. The following options files are
+   searched for in each directory and, if found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-rep-list.options
+   \
+
+   The following \cb{rep-list} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/bpkg/rep-remove.cli b/bpkg/rep-remove.cli
index de92271..aea0571 100644
--- a/bpkg/rep-remove.cli
+++ b/bpkg/rep-remove.cli
@@ -52,4 +52,25 @@ namespace bpkg
       "Clean the repository state."
     }
   };
+
+  "
+   \h|DEFAULT OPTIONS FILES|
+
+   See \l{bpkg-default-options-files(1)} for an overview of the default
+   options files. For the \cb{pkg-rep-remove} command the search start
+   directory is the configuration directory. The following options files are
+   searched for in each directory and, if found, loaded in the order listed:
+
+   \
+   bpkg.options
+   bpkg-rep-remove.options
+   \
+
+   The following \cb{rep-remove} command options cannot be specified in the
+   default options files:
+
+   \
+   --directory|-d
+   \
+  "
 }
diff --git a/doc/buildfile b/doc/buildfile
index d1e80b2..6d3097d 100644
--- a/doc/buildfile
+++ b/doc/buildfile
@@ -34,7 +34,8 @@ define xhtml: doc
 xhtml{*}: extension = xhtml
 
 ./: {man1 xhtml}{bpkg bpkg-common-options bpkg-repository-signing    \
-                 bpkg-repository-types bpkg-argument-grouping $cmds} \
+                 bpkg-repository-types bpkg-argument-grouping        \
+                 bpkg-default-options-files $cmds}                   \
     css{common pre-box man}                                          \
     file{man-*}
 
diff --git a/doc/cli.sh b/doc/cli.sh
index 7ad18f4..47601ad 100755
--- a/doc/cli.sh
+++ b/doc/cli.sh
@@ -61,13 +61,14 @@ compile "bpkg" $o --output-prefix "" --suppress-undocumented --class-doc bpkg::c
 
 compile "pkg-build" $o --class-doc  bpkg::pkg_build_pkg_options=exclude-base
 
-# NOTE: remember to update a similar list in buildfile.
+# NOTE: remember to update a similar list in buildfile and bpkg.cli as well as
+# the help topics sections in bpkg/buildfile and help.cxx.
 #
 pages="cfg-create help pkg-clean pkg-configure pkg-disfigure \
 pkg-drop pkg-fetch pkg-checkout pkg-install pkg-purge pkg-status pkg-test \
 pkg-uninstall pkg-unpack pkg-update pkg-verify rep-add rep-remove rep-list \
 rep-create rep-fetch rep-info repository-signing repository-types \
-argument-grouping"
+argument-grouping default-options-files"
 
 for p in $pages; do
   compile $p $o