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.

1 files changed, 3 insertions, 0 deletions

diff --git a/NEWS b/NEWS
index a3250161f..8d94f9e3c 100644
--- a/NEWS
+++ b/NEWS
@@ -112,6 +112,9 @@ GNU coreutils NEWS                                    -*- outline -*-
   cksum now accepts the --raw option to output a raw binary checksum.
   No file name or other information is output in this mode.
 
+  cp, mv, and install now accept the --debug option to
+  print details on how a file is being copied.
+
   factor now accepts the --exponents (-h) option to print factors
   in the form p^e, rather than repeating the prime p, e times.