From fa7c993ef9a2bb738b7a56ded76924c5cc730d85 Mon Sep 17 00:00:00 2001
From: Brad King <brad.king@kitware.com>
Date: Mon, 2 Mar 2026 11:58:09 -0500
Subject: [PATCH] Help: Document plain `ctest` command-line signature and exit
 code

---
 Help/manual/ctest.1.rst | 42 ++++++++++++++++++++++++++++++++++-------
 1 file changed, 35 insertions(+), 7 deletions(-)

diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst
index 03d11540e2..9167bd5184 100644
--- a/Help/manual/ctest.1.rst
+++ b/Help/manual/ctest.1.rst
@@ -11,7 +11,7 @@ Synopsis
 .. parsed-literal::
 
  `Run Tests`_
-  ctest [<options>] [--test-dir <path-to-build>]
+  ctest [<options>...] [--test-dir <path-to-build>]
 
  `Build and Test Mode`_
   ctest --build-and-test <path-to-source> <path-to-build>
@@ -42,6 +42,26 @@ This program will run the tests and report results.
 Run Tests
 =========
 
+:program:`ctest` runs tests defined by a ``CTestTestfile.cmake`` file,
+typically in a build tree generated by :manual:`cmake(1)`:
+
+.. code-block:: shell
+
+  ctest [<options>...] [--test-dir <path-to-build>]
+
+If all tests pass, the exit code is ``0``.  The exit code is non-zero
+in the following cases:
+
+* An error occurs, such as failure to process invalid arguments.
+
+* The :option:`--no-tests=error <ctest --no-tests>` argument is given and no
+  tests are executed, e.g., when ``CTestTestfile.cmake`` defines no tests,
+  or when the given arguments exclude all tests.
+
+* At least one test fails.
+
+The options for running tests are:
+
 .. program:: ctest
 
 .. option:: --preset <preset>, --preset=<preset>
@@ -484,13 +504,21 @@ Run Tests
 
 .. option:: --no-tests=<action>
 
- Regard no tests found either as error (when ``<action>`` is set to
- ``error``) or ignore it (when ``<action>`` is set to ``ignore``).
+ Specify behavior when no tests are executed, e.g., when
+ ``CTestTestfile.cmake`` defines no tests, or when the given arguments
+ exclude all tests.  The ``<action>`` may be one of:
 
- If no tests were found, the default behavior of CTest is to always log an
- error message but to return an error code in script mode only.  This option
- unifies the behavior of CTest by either returning an error code if no tests
- were found or by ignoring it.
+ ``error``
+   Consider running no tests to be an error.
+
+   This is the default when running :option:`ctest -S` scripts.
+
+ ``ignore``
+   Consider running no tests to be normal.
+
+   This is the default when `running tests <Run Tests_>`__ via the
+   :program:`ctest` command line, even when running as a
+   `dashboard client <Dashboard Client_>`__.
 
  .. versionadded:: 3.26