Subject: Re: bug#75582: GNU grep 3.4 — enhancing manual

From: sur-behoffski <[email-masked]>
Date: Fri, 17 Jan 2025 13:58:30 +1030

On 2025-01-16 15:32, Jim Meyering wrote:
> On Wed, Jan 15, 2025 at 8:16 PM sur-behoffski
> <[email-masked]> wrote:
> [...]> 
> Thanks for the suggestions. I went with Paul's (keeping it concise is
> important), so --help now prints this:
> 
> When FILE is '-', read standard input.  If no FILE is given, read standard
> input, but with -r, recursively search the working directory instead.  With
> fewer than two FILEs, assume -h.  Exit status is 0 if any line is selected,
> 1 otherwise; if any error occurs and -q is not given, the exit status is 2.
> 
> Here's the commit:
> https://git.savannah.gnu.org/cgit/grep.git/commit/?id=v3.11-56-gfc6aba9
> 
> Marking this as done.

----------------------------

Blending in documentation about -h immediately made me curious.
I've tried a quick test, and it seems grep 3.11's behaviour
doesn't match the new documentation:

        ~ $ mkdir grep-r
        ~ $ cd !$
        cd grep-r
        ~/grep-r $ echo "Hello, world" >single.txt
        ~/grep-r $ grep -r llo
        single.txt:Hello, world
        ~/grep-r $ ls -al
        total 12
        drwxr-xr-x  2 bjh bjh 4096 Jan 17 13:30 .
        drwx--x--x 38 bjh bjh 4096 Jan 17 13:30 ..
        -rw-r--r--  1 bjh bjh   13 Jan 17 13:30 single.txt
        ~/grep-r $ grep --version
        grep (GNU grep) 3.11
        Copyright (C) 2023 Free Software Foundation, Inc.
        License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
        This is free software: you are free to change and redistribute it.
        There is NO WARRANTY, to the extent permitted by law.

        Written by Mike Haertel and others; see
        <https://git.savannah.gnu.org/cgit/grep.git/tree/AUTHORS>.

    grep -P uses PCRE2 10.44 2024-06-07
        ~/grep-r $ 

Note the match prefix "single.txt:" above.

----------------------------

Looking at grep's documentation for -h:

       -h, --no-filename
              Suppress  the  prefixing  of file names on output.  This is the default when there is
              only one file (or only standard input) to search.

----------------------------

The discrepancy arises because recursion might dig up only
a single file to search, yet the assumption is that if -r is
specified (use recursion), simply assume many files, i.e.:

        -H, --with-filename
              Print the file name for each match.  This is the default when there is more than  one
              file to search.  This is a GNU extension.

I believe the behaviour is reasonable, as grep doesn't want
to get deeply into file counting associated with recursion,
but the behaviour mismatches the new documentation.

Reading the above a bit more, there may be confusion in the
documentation between "one file" and "one FILE" in the -h
entry.  Also, an additional "-r implies -H" clause might be
worthwhile in e.g. the -r documentation. 

----------------------------

Hope this helps,

s-b