Subject: bug#61720: closed (Re: bug#61720: BUG: omission of crucial detail in 'chown --reference' man page (vs info))

From: [email-masked] (GNU bug Tracking System)
Date: Thu, 23 Feb 2023 15:29:03 +0000

Your bug report

#61720: BUG: omission of crucial detail in 'chown --reference' man page (vs info)

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].

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

Subject: Re: bug#61720: BUG: omission of crucial detail in 'chown --reference' man page (vs info)
From: Pádraig Brady <[email-masked]>
To: Michael Coleman <[email-masked]>, [email-masked]
Date: Thu, 23 Feb 2023 15:28:18 +0000
List-Id: <debbugs-submit.debbugs.gnu.org>

On 22/02/2023 22:07, Michael Coleman wrote:
> Hi,
> 
> The (RHEL 7) man page for GNU 'chown' has (only) this for the '--reference' flag:
> 
>      use RFILE's owner and group rather than specifying OWNER:GROUP values
> 
> which omits the crucial second sentence, included in the info tree:
> 
>       Change the user and group of each FILE to be the same as those of
>       REF_FILE.  If REF_FILE is a symbolic link, do not use the user and
>       group of the symbolic link, but rather those of the file it refers
>       to.
> 
> (Note that '--no-deference' doesn't affect this behavior.)
> 
> I can't be sure, but I think the GNU build itself is generating this man page, as opposed to it having been created by RHEL.
> 
> I understand that the man pages are secondary and brief, but they shouldn't be actively misleading, IMO.

It is worth stating that in the man page,
especially since one might think --no-dereference might change behavior.

Fixing this with the attached.

Marking this as done.

thanks,
Pádraig

From c97c40c3b4f5338b1c8689002f50d523b9cff2a0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email-masked]>
Date: Thu, 23 Feb 2023 15:22:14 +0000
Subject: [PATCH] doc: chgrp,chmod,chown: state --reference always dereferences

* src/chgrp.c (usage): State that --reference always
dereferences symbolic links.
* src/chmod.c (usage): Likewise.
* src/chown.c (usage): Likewise.
Fixes https://bugs.gnu.org/61720
---
 src/chgrp.c | 4 ++--
 src/chmod.c | 3 ++-
 src/chown.c | 4 ++--
 3 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/src/chgrp.c b/src/chgrp.c
index e695328e9..141413352 100644
--- a/src/chgrp.c
+++ b/src/chgrp.c
@@ -136,8 +136,8 @@ With --reference, change the group of each FILE to that of RFILE.\n\
       --preserve-root    fail to operate recursively on '/'\n\
 "), stdout);
       fputs (_("\
-      --reference=RFILE  use RFILE's group rather than specifying a\n\
-                         GROUP value\n\
+      --reference=RFILE  use RFILE's group rather than specifying a GROUP.\n\
+                         RFILE is always dereferenced if a symbolic link.\n\
 "), stdout);
       fputs (_("\
   -R, --recursive        operate on files and directories recursively\n\
diff --git a/src/chmod.c b/src/chmod.c
index a0b83a8f7..e48736e11 100644
--- a/src/chmod.c
+++ b/src/chmod.c
@@ -393,7 +393,8 @@ With --reference, change the mode of each FILE to that of RFILE.\n\
       --preserve-root    fail to operate recursively on '/'\n\
 "), stdout);
       fputs (_("\
-      --reference=RFILE  use RFILE's mode instead of MODE values\n\
+      --reference=RFILE  use RFILE's mode instead of specifying MODE values.\n\
+                         RFILE is always dereferenced if a symbolic link.\n\
 "), stdout);
       fputs (_("\
   -R, --recursive        change files and directories recursively\n\
diff --git a/src/chown.c b/src/chown.c
index f298b6081..d4ae24bec 100644
--- a/src/chown.c
+++ b/src/chown.c
@@ -113,8 +113,8 @@ With --reference, change the owner and group of each FILE to those of RFILE.\n\
       --preserve-root    fail to operate recursively on '/'\n\
 "), stdout);
       fputs (_("\
-      --reference=RFILE  use RFILE's owner and group rather than\n\
-                         specifying OWNER:GROUP values\n\
+      --reference=RFILE  use RFILE's owner and group rather than specifying\n\
+                         OWNER:GROUP values.  RFILE is always dereferenced.\n\
 "), stdout);
       fputs (_("\
   -R, --recursive        operate on files and directories recursively\n\
-- 
2.26.2

Subject: BUG: omission of crucial detail in 'chown --reference' man page (vs info)
From: Michael Coleman <[email-masked]>
To: "[email-masked]" <[email-masked]>
Date: Wed, 22 Feb 2023 22:07:27 +0000
List-Id: <debbugs-submit.debbugs.gnu.org>

Hi,

The (RHEL 7) man page for GNU 'chown' has (only) this for the '--reference' flag:

    use RFILE's owner and group rather than specifying OWNER:GROUP values

which omits the crucial second sentence, included in the info tree:

     Change the user and group of each FILE to be the same as those of
     REF_FILE.  If REF_FILE is a symbolic link, do not use the user and
     group of the symbolic link, but rather those of the file it refers
     to.

(Note that '--no-deference' doesn't affect this behavior.)

I can't be sure, but I think the GNU build itself is generating this man page, as opposed to it having been created by RHEL.

I understand that the man pages are secondary and brief, but they shouldn't be actively misleading, IMO.

Thanks,
Mike

Michael Coleman
Computational Scientist
Research Advanced Computing Services (HPC)
University of Oregon