From 862185ee1fc89f680ba56217e633a9a6ee60dd9e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Colomb?= Date: Sun, 7 Jun 2026 21:24:01 +0200 Subject: [PATCH 1/4] Stop referring to removed --reset-deltas option. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This was removed in Syncthing v2. Simply avoid mentioning it. Signed-off-by: André Colomb --- users/config.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/users/config.rst b/users/config.rst index 7b5d08ff..c5da3954 100644 --- a/users/config.rst +++ b/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 From 948fa2cb761d321651f4087eded271f7440a4183 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Colomb?= Date: Sun, 7 Jun 2026 21:43:27 +0200 Subject: [PATCH 2/4] Describe debug subcommand similar to the cli hierarchy. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clarify that "cli debug" commands do not require Syncthing to be stopped, while in fact removing the database completely should not be done while it is running. Point to the corresponding API endpoint /rest/system/reset for more granular DB reset functionality. Signed-off-by: André Colomb --- includes/cli-commands.rst | 3 +-- includes/debug-commands.rst | 14 ++++++++++++++ users/syncthing.rst | 8 ++++++++ 3 files changed, 23 insertions(+), 2 deletions(-) create mode 100644 includes/debug-commands.rst diff --git a/includes/cli-commands.rst b/includes/cli-commands.rst index c4790723..fcd3d5be 100644 --- a/includes/cli-commands.rst +++ b/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 diff --git a/includes/debug-commands.rst b/includes/debug-commands.rst new file mode 100644 index 00000000..0d34c47c --- /dev/null +++ b/includes/debug-commands.rst @@ -0,0 +1,14 @@ +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. diff --git a/users/syncthing.rst b/users/syncthing.rst index 07bfd010..6213ede1 100644 --- a/users/syncthing.rst +++ b/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 ------- From 4774b731d8dd5dcd969eda593f88228abbaed632 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Colomb?= Date: Sun, 7 Jun 2026 21:47:53 +0200 Subject: [PATCH 3/4] Add a label for the reset-database subcommand. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Currently not used as a target anywhere, but might prove useful for a future FAQ. Add the includes top-level directory to the exclusion list for Sphinx. Documents in there are always used via an include:: directive, so processing them as (unreachable) standalone documents leads to duplicate label warnings. Signed-off-by: André Colomb --- conf.py | 2 +- includes/debug-commands.rst | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/conf.py b/conf.py index 62f2ff2a..5c4aeab6 100644 --- a/conf.py +++ b/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. diff --git a/includes/debug-commands.rst b/includes/debug-commands.rst index 0d34c47c..f2cf0625 100644 --- a/includes/debug-commands.rst +++ b/includes/debug-commands.rst @@ -1,3 +1,5 @@ +.. _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 From 7ce8dba1a496de4f00b4a0fe16dadfda2f9615b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Colomb?= Date: Sun, 7 Jun 2026 21:50:50 +0200 Subject: [PATCH 4/4] Fix obsolete reference to --reset-database option. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The cautionary note was removed in v2 together with the whole option. Resurrect the text from the old option doc. Signed-off-by: André Colomb --- rest/system-reset-post.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/rest/system-reset-post.rst b/rest/system-reset-post.rst index fd9bd444..d2c82e20 100644 --- a/rest/system-reset-post.rst +++ b/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.