file: add `COPY_FILE` subcommand

The `file(COPY)` subcommand is overloaded and busy for such a simple
operation. Instead, make a simpler subcommand with error handling
support.

2 files changed, 27 insertions, 0 deletions

diff --git a/Help/command/file.rst b/Help/command/file.rst
index 9cde90c..445a408 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -39,6 +39,7 @@ Synopsis
   `Filesystem`_
     file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...])
     file(`RENAME`_ <oldname> <newname> [...])
+    file(`COPY_FILE`_ <oldname> <newname> [...])
     file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...])
     file(`MAKE_DIRECTORY`_ [<dir>...])
     file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...])
@@ -683,6 +684,28 @@ The options are:
   If ``RESULT <result>`` is used, the result variable will be
   set to ``NO_REPLACE``.  Otherwise, an error is emitted.
 
+.. _COPY_FILE:
+
+.. code-block:: cmake
+
+  file(COPY_FILE <oldname> <newname>
+       [RESULT <result>]
+       [ONLY_IF_DIFFERENT])
+
+Copy a file from ``<oldname>`` to ``<newname>``. Directories are not
+supported. Symlinks are ignored and ``<oldfile>``'s content is read and
+written to ``<newname>`` as a new file.
+
+The options are:
+
+``RESULT <result>``
+  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.
+
+``ONLY_IF_DIFFERENT``
+  If the ``<newname>`` path already exists, do not replace it if it is the
+  same as ``<oldname>``. Otherwise, an error is emitted.
+
 .. _REMOVE:
 .. _REMOVE_RECURSE:
 
diff --git a/Help/release/dev/file-COPY_FILE.rst b/Help/release/dev/file-COPY_FILE.rst
new file mode 100644
index 0000000..2f0cdf0
--- /dev/null
+++ b/Help/release/dev/file-COPY_FILE.rst
@@ -0,0 +1,4 @@
+file-COPY_ONLY
+--------------
+
+* The :command:`file(COPY_FILE)` command was added to copy a file to another.