file(RENAME): Add option to not replace existing path

Add a `NO_REPLACE` option that prevents overwriting `<newname>`
if it exists.

2 files changed, 9 insertions, 2 deletions

diff --git a/Help/command/file.rst b/Help/command/file.rst
index b28e206..9cde90c 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -666,7 +666,8 @@ Examples of recursive globbing include::
 .. code-block:: cmake
 
   file(RENAME <oldname> <newname>
-       [RESULT <result>])
+       [RESULT <result>]
+       [NO_REPLACE])
 
 Move a file or directory within a filesystem from ``<oldname>`` to
 ``<newname>``, replacing the destination atomically.
@@ -677,6 +678,11 @@ The options are:
   Set ``<result>`` variable to ``0`` on success or an error message otherwise.
   If ``RESULT`` is not specified and the operation fails, an error is emitted.
 
+``NO_REPLACE``
+  If the ``<newname>`` path already exists, do not replace it.
+  If ``RESULT <result>`` is used, the result variable will be
+  set to ``NO_REPLACE``.  Otherwise, an error is emitted.
+
 .. _REMOVE:
 .. _REMOVE_RECURSE:
 
diff --git a/Help/release/dev/file-RENAME.rst b/Help/release/dev/file-RENAME.rst
index 6cde036..6c1314d 100644
--- a/Help/release/dev/file-RENAME.rst
+++ b/Help/release/dev/file-RENAME.rst
@@ -2,4 +2,5 @@ file-RENAME
 -----------
 
 * The :command:`file(RENAME)` command learned to optionally capture
-  failure in a result variable.
+  failure in a result variable.  It also gained a ``NO_REPLACE``
+  option to fail if the destination exists.