FetchContent: Force cmake --fresh to re-execute direct population steps

Issue: #25468

3 files changed, 21 insertions, 6 deletions

diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index afabb75..48a9219 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -213,6 +213,13 @@ Options
  This removes any existing ``CMakeCache.txt`` file and associated
  ``CMakeFiles/`` directory, and recreates them from scratch.
 
+ .. versionchanged:: 3.30
+
+   For dependencies previously populated by :module:`FetchContent` with the
+   ``NEW`` setting for policy :policy:`CMP0168`, their stamp and script files
+   from any previous run will be removed. The download, update, and patch
+   steps will therefore be forced to re-execute.
+
 .. option:: -L[A][H]
 
  List non-advanced cached variables.
@@ -1381,9 +1388,8 @@ The options are:
 
 .. option:: --fresh
 
-  Perform a fresh configuration of the build tree.
-  This removes any existing ``CMakeCache.txt`` file and associated
-  ``CMakeFiles/`` directory, and recreates them from scratch.
+  Perform a fresh configuration of the build tree, which has the same effect
+  as :option:`cmake --fresh`.
 
 View Help
 =========
diff --git a/Help/policy/CMP0168.rst b/Help/policy/CMP0168.rst
index 8317351..cab40b9 100644
--- a/Help/policy/CMP0168.rst
+++ b/Help/policy/CMP0168.rst
@@ -31,6 +31,11 @@ The ``NEW`` behavior has the following characteristics:
 * The ``PREFIX``, ``TMP_DIR``, ``STAMP_DIR``, ``LOG_DIR``, and ``DOWNLOAD_DIR``
   options and their associated directory properties are ignored. The
   :module:`FetchContent` module controls those locations internally.
+* :option:`cmake --fresh` will remove the stamp and script files used for
+  tracking and populating the dependency. This will force the dependency's
+  download, update, and patch steps to be re-executed. The directory used for
+  downloads is not affected by :option:`cmake --fresh`, so any previously
+  downloaded files for the ``URL`` download method can still be re-used.
 
 The ``OLD`` behavior has the following characteristics:
 
@@ -44,6 +49,9 @@ The ``OLD`` behavior has the following characteristics:
   update, or patch steps are supported.
 * If the ``QUIET`` option is used, or the :variable:`FETCHCONTENT_QUIET`
   variable is set to true, warnings will not be shown in the output.
+* :option:`cmake --fresh` has no effect on the dependency's stamp or script
+  files. Previously executed steps will only re-run if details about the
+  dependency have changed.
 
 There's a reasonably good chance that users can set the
 :variable:`CMAKE_POLICY_DEFAULT_CMP0168 <CMAKE_POLICY_DEFAULT_CMP<NNNN>>`
diff --git a/Help/release/3.30.rst b/Help/release/3.30.rst
index 8c8bb85..dc0d573 100644
--- a/Help/release/3.30.rst
+++ b/Help/release/3.30.rst
@@ -224,9 +224,10 @@ Other Changes
 * :module:`FetchContent` now prefers to populate content directly rather
   than using a separate sub-build. This may significantly improve configure
   times on some systems (Windows especially, but also on macOS when using
-  the Xcode generator). Policy :policy:`CMP0168` provides backward
-  compatibility for those projects that still rely on using a sub-build for
-  content population.
+  the Xcode generator). :option:`cmake --fresh` also forces the download,
+  update, and patch steps of directly populated dependencies to be re-executed.
+  Policy :policy:`CMP0168` provides backward compatibility for those projects
+  that still rely on using a sub-build for content population.
 
 * When :variable:`FETCHCONTENT_FULLY_DISCONNECTED` is set to true,
   :command:`FetchContent_MakeAvailable` and the single-argument form of