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

From: [email-masked] (GNU bug Tracking System)
Date: Sat, 09 Apr 2022 12:07:02 +0000

Your bug report

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

which was filed against the coreutils package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
50889: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=50889
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#50889: Please improve the documentation for install --compare (-C)
From: Pádraig Brady <[email-masked]>
To: Ian Cross <[email-masked]>, [email-masked]
Date: Sat, 9 Apr 2022 13:06:28 +0100
List-Id: <debbugs-submit.debbugs.gnu.org>

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

Subject: Please improve the documentation for install --compare (-C)
From: Ian Cross <[email-masked]>
To: [email-masked]
Date: Wed, 29 Sep 2021 12:09:15 +0100
List-Id: <debbugs-submit.debbugs.gnu.org>

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?

Thanks

Ian