Subject: Re: bug#50889: Please improve the documentation for install --compare (-C)

From: Pádraig Brady <[email-masked]>
Date: Sat, 9 Apr 2022 13:06:28 +0100

On 29/09/2021 12:09, Ian Cross via GNU coreutils Bug Reports wrote:
> Hi,
> 
> A while back a request was made to improve the documentation of the
> `install --compare` cmd:
> 
> https://lists.gnu.org/archive/html/bug-coreutils/2009-09/msg00029.html
> 
> It seems the wording in `coreutils.texi` has been updated since
> (https://github.com/coreutils/coreutils/commit/c8ac385299950ba84eb8c33f7e32e4d85b18e3ff
> ) but the manpage and `--help` as of coreutils v8.32 still leave things
> vague:
> 
>> compare each pair of source and destination files, and in some cases,
> do not modify the destination at all
> 
> Florain Schlichting at the time of the request suggested this wording
> instead:
> 
>> compare each pair of source and destination files, and if identical
> (by content, ownership and mode), do not copy to preserve mtime
> 
> It looks like a patch was made but somehow never made it into the
> codebase. Please could the manpage and help be updated with this
> wording so users can understand more readily what compare will do?

Both the --help and texinfo was incomplete / confusing.
I've installed the attached to address this.

Marking this as done.

thanks,
Pádraig
From 6d246fb68b7d8fcd6e7b3da88bd786b305f40f32 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email-masked]>
Date: Sat, 9 Apr 2022 12:42:37 +0100
Subject: [PATCH] doc: install --compare: clarify mode of operation

* doc/coreutils.texi (install invocation): For the --compare option,
clarify that the ownership or permissions of the source files don't
matter.  Also don't imply --owner or --group need to be specified
for --compare to be effective.
* src/install.c (usage): Add more detail on what's being compared.
---
 doc/coreutils.texi | 4 ++--
 src/install.c      | 5 +++--
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index c9243c683..8cfa698a1 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -9796,8 +9796,8 @@ The program accepts the following options.  Also see @ref{Common options}.
 @itemx --compare
 @opindex -C
 @opindex --compare
-Compare each pair of source and destination files, and if the destination has
-identical content and any specified owner, group, permissions, and possibly
+Compare content of source and destination files, and if there would be no
+change to the destination content, owner, group, permissions, and possibly
 SELinux context, then do not modify the destination at all.
 Note this option is best used in conjunction with @option{--user},
 @option{--group} and @option{--mode} options, lest @command{install}
diff --git a/src/install.c b/src/install.c
index 57a877f4a..079ce1f70 100644
--- a/src/install.c
+++ b/src/install.c
@@ -592,8 +592,9 @@ In the 4th form, create all components of the given DIRECTORY(ies).\n\
       --backup[=CONTROL]  make a backup of each existing destination file\n\
   -b                  like --backup but does not accept an argument\n\
   -c                  (ignored)\n\
-  -C, --compare       compare each pair of source and destination files, and\n\
-                        in some cases, do not modify the destination at all\n\
+  -C, --compare       compare content of source and destination files, and\n\
+                        if no change to content, ownership, and permissions,\n\
+                        do not modify the destination at all\n\
   -d, --directory     treat all arguments as directory names; create all\n\
                         components of the specified directories\n\
 "), stdout);
-- 
2.26.2