cp,install,mv: add --debug to explain how a file is copied

How a file is copied is dependent on the sparseness of the file,
what file system it is on, what file system the destination is on,
the attributes of the file, and whether they're being copied or not.
Also the --reflink and --sparse options directly impact the operation.

Given it's hard to reason about the combination of all of the above,
the --debug option is useful for users to directly identify if
copy offloading, reflinking, or sparse detection are being used.

It will also be useful for tests to directly query if
these operations are supported.

The new output looks as follows:

  $ src/cp --debug src/cp file.sparse
  'src/cp' -> 'file.sparse'
  copy offload: yes, reflink: unsupported, sparse detection: no

  $ truncate -s+1M file.sparse

  $ src/cp --debug file.sparse file.sparse.cp
  'file.sparse' -> 'file.sparse.cp'
  copy offload: yes, reflink: unsupported, sparse detection: SEEK_HOLE

  $ src/cp --reflink=never --debug file.sparse file.sparse.cp
  'file.sparse' -> 'file.sparse.cp'
  copy offload: avoided, reflink: no, sparse detection: SEEK_HOLE

* doc/coreutils.texi (cp invocation): Describe the --debug option.
(mv invocation): Likewise.
(install invocation): Likewise.
* src/copy.h: Add a new DEBUG member to cp_options, to control
whether to output debug info or not.
* src/copy.c (copy_debug): A new global structure to
unconditionally store debug into from the last copy_reg operations.
(copy_debug_string, emit_debug): New functions to print debug info.
* src/cp.c: if ("--debug") x->debug=true;
* src/install.c: Likewise.
* src/mv.c: Likewise.
* tests/cp/debug.sh: Add a new test.
* tests/local.mk: Reference the new test.
* NEWS: Mention the new feature.

2 files changed, 29 insertions, 0 deletions

diff --git a/tests/cp/debug.sh b/tests/cp/debug.sh
new file mode 100755
index 000000000..b46adc637
--- /dev/null
+++ b/tests/cp/debug.sh
@@ -0,0 +1,28 @@
+#!/bin/sh
+# Ensure that cp --debug works as documented
+
+# Copyright (C) 2023 Free Software Foundation, Inc.
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+. "${srcdir=.}/tests/init.sh"; path_prepend_ ./src
+print_ver_ cp
+
+touch file || framework_failure_
+cp --debug file file.cp >cp.out || fail=1
+grep 'copy offload:.*reflink:.*sparse detection:' cp.out || fail=1
+cp --debug --attributes-only file file.cp >cp.out || fail=1
+returns_ 1 grep 'copy offload:.*reflink:.*sparse detection:' cp.out || fail=1
+
+Exit $fail
diff --git a/tests/local.mk b/tests/local.mk
index 4c40fd115..c8db95e99 100644
--- a/tests/local.mk
+++ b/tests/local.mk
@@ -484,6 +484,7 @@ all_tests =					\
   tests/cp/cp-i.sh				\
   tests/cp/cp-mv-backup.sh			\
   tests/cp/cp-parents.sh			\
+  tests/cp/debug.sh				\
   tests/cp/deref-slink.sh			\
   tests/cp/dir-rm-dest.sh			\
   tests/cp/dir-slash.sh				\