chore: clarify database resetting options

conf.py

@@ -92,7 +92,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build', '_syncthing', 'draft', 'README.rst', 'users/faq-parts']
+exclude_patterns = ['_build', '_syncthing', 'draft', 'README.rst', 'users/faq-parts', 'includes']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

includes/cli-commands.rst

@@ -24,8 +24,7 @@ errors
 
 debug
     Various tools to aid in diagnosing problems or collection information for
-    bug reports.  Some of these commands access the database directly and can
-    therefore only work when Syncthing is not running.
+    bug reports.
 
 ``-`` (a single dash)
     Reads subsequent commands from the standard input stream, without needing to

includes/debug-commands.rst

@@ -0,0 +1,16 @@
+.. _reset-database:
+
+debug reset-database
+    Reset the database, forcing a full rescan and resync.  **Must only be used
+    when Syncthing is not running.**  More granular reset operations are
+    available on the REST API while Syncthing is running:
+    :doc:`../rest/system-reset-post`
+
+debug database-statistics
+    Display database size statistics.
+
+debug database-counts
+    Display database folder counts.
+
+debug database-file
+    Display database file metadata.

rest/system-reset-post.rst

@@ -10,5 +10,7 @@ information for that folder will be erased:
 
         curl -X POST -H "X-API-Key: abc123" http://localhost:8384/rest/system/reset?folder=ab1c2-def3g
 
-**Caution**: See :option:`--reset-database` for ``.stfolder`` creation
-side-effect and caution regarding mountpoints.
+Creates ``.stfolder`` folders in each sync folder if they do not already exist.
+**Caution**: Ensure that all sync folders which are mountpoints are already
+mounted.  Inconsistent versions may result if the mountpoint is later mounted
+and contains older versions.

users/config.rst

@@ -1337,11 +1337,10 @@ The ``options`` element contains all other global configuration options.
 
 .. option:: options.sendFullIndexOnUpgrade
 
-    Controls whether all index data is resent when an upgrade has happened,
-    equivalent to starting Syncthing with :option:`--reset-deltas`.  This used
-    to be the default behavior in older versions, but is mainly useful as a
-    troubleshooting step and causes high database churn. The default is now
-    ``false``.
+    Controls whether all index data is resent when an upgrade has happened.
+    This used to be the default behavior in older versions, but is mainly useful
+    as a troubleshooting step and causes high database churn.  The default is
+    now ``false``.
 
 .. option:: options.featureFlag
     :aliases: options.featureFlags

users/syncthing.rst

@@ -323,6 +323,14 @@ saves the hassle of handling HTTP connections and API authentication.
 
 .. include:: ../includes/cli-commands.rst
 
+For troubleshooting issues, the ``debug`` subcommand provides some commonly
+needed actions for data analysis and repair.  Some of these commands access the
+database directly and can therefore only work when Syncthing is not running.
+Not to be confused with the ``cli debug`` subcommand group, which works via the
+REST API.
+
+.. include:: ../includes/debug-commands.rst
+
 Proxies
 -------