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?= <p...@draigbrady.com>
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
