Merge topic 'ctest-update-version-override'

2a34d0ac36 ctest: Add new variable CTEST_UPDATE_VERSION_OVERRIDE
7ddac95121 Help: cross-ref and wording of docs related to ctest_update()
a0d04d8810 testing: Update terminology in ctest_update tests

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Zack Galbreath <zack.galbreath@kitware.com>
Merge-request: !3277

Help/command/ctest_update.rst

@@ -35,4 +35,5 @@ The options are:
 
 The update always follows the version control branch currently checked
 out in the source directory.  See the :ref:`CTest Update Step`
-documentation for more information.
+documentation for information about variables that change the behavior
+of ``ctest_update()``.

Help/manual/cmake-variables.7.rst

@@ -583,6 +583,7 @@ Variables for CTest
    /variable/CTEST_UPDATE_COMMAND
    /variable/CTEST_UPDATE_OPTIONS
    /variable/CTEST_UPDATE_VERSION_ONLY
+   /variable/CTEST_UPDATE_VERSION_OVERRIDE
    /variable/CTEST_USE_LAUNCHERS
 
 Variables for CPack

Help/manual/ctest.1.rst

@@ -822,6 +822,8 @@ Configuration settings to specify the version control tool include:
   * :module:`CTest` module variable: ``UPDATE_TYPE`` if set,
     else ``CTEST_UPDATE_TYPE``
 
+.. _`UpdateVersionOnly`:
+
 ``UpdateVersionOnly``
   Specify that you want the version control update command to only
   discover the current version that is checked out, and not to update
@@ -829,6 +831,18 @@ Configuration settings to specify the version control tool include:
 
   * `CTest Script`_ variable: :variable:`CTEST_UPDATE_VERSION_ONLY`
 
+.. _`UpdateVersionOverride`:
+
+``UpdateVersionOverride``
+  Specify the current version of your source tree.
+
+  When this variable is set to a non-empty string, CTest will report the value
+  you specified rather than using the update command to discover the current
+  version that is checked out. Use of this variable supersedes
+  ``UpdateVersionOnly``. Like ``UpdateVersionOnly``, using this variable tells
+  CTest not to update the source tree to a different version.
+
+  * `CTest Script`_ variable: :variable:`CTEST_UPDATE_VERSION_OVERRIDE`
 
 Additional configuration settings include:
 

Help/release/dev/ctest_update_version_override.rst

@@ -0,0 +1,7 @@
+CTEST_UPDATE_VERSION_OVERRIDE
+-----------------------------
+
+* The :command:`ctest_update` command learned to honor a new variable:
+  :variable:`CTEST_UPDATE_VERSION_OVERRIDE`. This can be used to specify
+  the current version of your source tree rather than using the update
+  command to discover the current version that is checked out.

Help/variable/CTEST_UPDATE_VERSION_ONLY.rst

@@ -1,5 +1,5 @@
 CTEST_UPDATE_VERSION_ONLY
 -------------------------
 
-Specify the CTest ``UpdateVersionOnly`` setting
+Specify the CTest :ref:`UpdateVersionOnly <UpdateVersionOnly>` setting
 in a :manual:`ctest(1)` dashboard client script.

Help/variable/CTEST_UPDATE_VERSION_OVERRIDE.rst

@@ -0,0 +1,5 @@
+CTEST_UPDATE_VERSION_OVERRIDE
+-----------------------------
+
+Specify the CTest :ref:`UpdateVersionOverride <UpdateVersionOverride>` setting
+in a :manual:`ctest(1)` dashboard client script.