bugfindutils - Bugs: bug #62259, find(1) manpage prune example error

 
 

bug #62259: find(1) manpage prune example error

Submitter:  raf <raf>
Submitted:  Wed 06 Apr 2022 02:57:55 PM UTC
   
 
Category:  documentation Severity:  3 - Normal
Item Group:  Wrong result Status:  Fixed
Privacy:  Public Assigned to:  berny
Originator Name:  raf Open/Closed:  Open
Release:  4.9.0 Fixed Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Fri 18 Apr 2025 11:08:04 AM UTC, comment #8: 

Fair enough - pushed:

- doc: supplement list of actions that suppress default -print
  https://git.sv.gnu.org/cgit/findutils.git/commit/?id=1ef8d7c2cf32bac218af011fb727262f940e6d78

- NEWS: mention the previous doc fixes
  https://git.sv.gnu.org/cgit/findutils.git/commit/?id=bad1de52aaa03b67a65bd7ca4c366dbdd22ef14e

- doc: fix the "Finding the Shallowest Instance" example in find.1
  https://git.sv.gnu.org/cgit/findutils.git/commit/?id=97b8920482d6fdfb18063b8bbbdd3dcf8bbd4357

- doc: fix the "Finding the Shallowest Instance" example in Texinfo manual
  https://git.sv.gnu.org/cgit/findutils.git/commit/?id=45530ee875e832c9691216bd1597ac54f8c118be

Marking this as fixed ... finally. :-)
Sorry for all the delays.

Bernhard Voelker <berny>
Group administrator
Mon 07 Apr 2025 11:31:39 PM UTC, comment #7: 

Rather than just changing the text "Sample output" to "Sample directories", I think it's much better to include the expected output as well (as my old patch did and as the original documentation attempted to do). Showing both teh input and output does a better job of demonstrating the behaviour.

raf <raf>
Mon 07 Apr 2025 09:06:17 PM UTC, comment #6: 

Alright, let's fix the errors - done with the 3 attached patches.

I'd like to leave the discussion about the best performance out
for now, as the point for this example is explaining -prune.

@Raf: ok to push?

(file #57115, file #57116, file #57117)

Bernhard Voelker <berny>
Group administrator
Fri 28 Feb 2025 06:00:30 PM UTC, comment #5: 

I was just looking to report this as well. I hope the patch to fix this glaring error in the manpage will be accepted soon.

Andrew Davis <adavis>
Sat 22 Oct 2022 11:56:51 PM UTC, comment #4: 

It looks like my "patches" didn't get included. I've just submitted a real patch for the manual entry and the texi file via git send-email.

raf <raf>
Tue 19 Apr 2022 12:01:01 PM UTC, comment #3: 

Here is a choice of two patches. The first fixes the initially reported problem (sample directories labelled as sample output and no corresponding sample output given). The second does that and also replaces the example command with one that is efficient.

raf <raf>
Fri 08 Apr 2022 12:30:42 PM UTC, comment #2: 

Another (unrelated) problem with this example is that it is supposed to be "an efficient search for the projects' roots", but it's not efficient (apart from the pruning). It invokes up to three test processes for every candidate file. It only needs to invoke a single test process (that checks for all three SCM sub-directories), and it only needs to do that for candidates that are actually directories. It's doing it for everything. That's a lot of unnecessary processes.

I suggest replacing this:

    $ find repo/ \
        \( -exec test -d '{}/.svn' \; \
        -or -exec test -d '{}/.git' \; \
        -or -exec test -d '{}/CVS' \; \
        \) -print -prune

with this:

    $ find repo \
        -type d \
        -exec test -d '{}/.svn' -o -e '{}/.git' -o -d '{}/CVS' \; \
        -print -prune

Bonus: The -e for {}/.git rather than -d is because .git can be a file that refers to a directory somewhere else.

raf <raf>
Wed 06 Apr 2022 09:46:45 PM UTC, comment #1: 

Confirmed:

horizon:~/tmp/find-example-bug-62259$ for d in repo/project1/CVS     repo/gnu/project2/.svn repo/gnu/project3/.svn repo/gnu/project3/src/.svn repo/project4/.git; do mkdir -p "$d" && touch "$d"/somefile ; done
horizon:~/tmp/find-example-bug-62259$ find repo/ \
        \( -exec test -d '{}/.svn' \; \
        -or -exec test -d '{}/.git' \; \
        -or -exec test -d '{}/CVS' \; \
        \) -print -prune
repo/project4
repo/project1
repo/gnu/project2
repo/gnu/project3
horizon:~/tmp/find-example-bug-62259$ find repo -ls
  1459999      1 drwxr-xr-x   5 james    james           5 Apr  6 22:43 repo
  1460014      1 drwxr-xr-x   3 james    james           3 Apr  6 22:43 repo/project4
  1460015      1 drwxr-xr-x   2 james    james           3 Apr  6 22:43 repo/project4/.git
  1460016      1 -rw-r--r--   1 james    james           0 Apr  6 22:43 repo/project4/.git/somefile
  1460000      1 drwxr-xr-x   3 james    james           3 Apr  6 22:43 repo/project1
  1460001      1 drwxr-xr-x   2 james    james           3 Apr  6 22:43 repo/project1/CVS
  1460002      1 -rw-r--r--   1 james    james           0 Apr  6 22:43 repo/project1/CVS/somefile
  1460003      1 drwxr-xr-x   4 james    james           4 Apr  6 22:43 repo/gnu
  1460004      1 drwxr-xr-x   3 james    james           3 Apr  6 22:43 repo/gnu/project2
  1460005      1 drwxr-xr-x   2 james    james           3 Apr  6 22:43 repo/gnu/project2/.svn
  1460006      1 -rw-r--r--   1 james    james           0 Apr  6 22:43 repo/gnu/project2/.svn/somefile
  1460007      1 drwxr-xr-x   4 james    james           4 Apr  6 22:43 repo/gnu/project3
  1460008      1 drwxr-xr-x   2 james    james           3 Apr  6 22:43 repo/gnu/project3/.svn
  1460009      1 -rw-r--r--   1 james    james           0 Apr  6 22:43 repo/gnu/project3/.svn/somefile
  1460011      1 drwxr-xr-x   3 james    james           3 Apr  6 22:43 repo/gnu/project3/src
  1460012      1 drwxr-xr-x   2 james    james           3 Apr  6 22:43 repo/gnu/project3/src/.svn
  1460013      1 -rw-r--r--   1 james    james           0 Apr  6 22:43 repo/gnu/project3/src/.svn/somefile

James Youngman <jay>
Group administrator
Wed 06 Apr 2022 02:57:55 PM UTC, original submission:  

In the find(1) manual entry, there is this example:

Given the following directory of projects and their associated   SCM administrative directories, perform an efficient search for the projects' roots:

    $ find repo/ \
        \( -exec test -d '{}/.svn' \; \
        -or -exec test -d '{}/.git' \; \
        -or -exec test -d '{}/CVS' \; \
        \) -print -prune

Sample output:

    repo/project1/CVS
    repo/gnu/project2/.svn
    repo/gnu/project3/.svn
    repo/gnu/project3/src/.svn
    repo/project4/.git

But the above sample output is very wrong. If the directories listed above existed, then the output would be:

  repo/project1
  repo/gnu/project2
  repo/gnu/project3
  repo/project4

(but not necessarily in that order).

The "/CVS" and "/.svn" and "/.git" sub-directories would not be included in the output because they don't match the query. It is their parent directories that match the query.

More importantly, the "repo/gnu/project3/src" directory would not appear because of the use of -prune which excludes anything under "repo/gnu/project3". That's the whole point of this example. It prunes the tree wherever it finds an SCM directory (so it excludes nested project roots).

It looks like the "Sample output" should really have been listed under "Given the following directory of projects", and the "Sample output" should have been completely different.

This example should probably be rewritten to look like this:

Given the following directory of projects and their associated   SCM administrative directories, perform an efficient search for the projects' roots:

    $ find repo/ \
        \( -exec test -d '{}/.svn' \; \
        -or -exec test -d '{}/.git' \; \
        -or -exec test -d '{}/CVS' \; \
        \) -print -prune

Sample directories:

    repo/project1/CVS
    repo/gnu/project2/.svn
    repo/gnu/project3/.svn
    repo/gnu/project3/src/.svn
    repo/project4/.git

Sample output:

    repo/project1
    repo/gnu/project2
    repo/gnu/project3
    repo/project4

raf <raf>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #57115:  0001-doc-fix-the-Finding-the-Shallowest-Instance-example-.patch added by berny (2KiB - text/x-patch - Patches fixing the issue in Texinfo + find.1, incl. NEWS entry)
file #57116:  0002-doc-fix-the-Finding-the-Shallowest-Instance-example-.patch added by berny (1KiB - text/x-patch - Patches fixing the issue in Texinfo + find.1, incl. NEWS entry)
file #57117:  0003-NEWS-mention-the-previous-doc-fixes.patch added by berny (947B - text/x-patch - Patches fixing the issue in Texinfo + find.1, incl. NEWS entry)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by berny (Updated the item)
  • -email is unavailable- added by adavis (Posted a comment)
  • -email is unavailable- added by jay (Posted a comment)
  • -email is unavailable- added by raf (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 6 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2025-04-18 berny StatusIn Progress Fixed
    2025-04-07 berny Attached File- Added 0001-doc-fix-the-Finding-the-Shallowest-Instance-example-.patch, #57115
        Attached File- Added 0002-doc-fix-the-Finding-the-Shallowest-Instance-example-.patch, #57116
        Attached File- Added 0003-NEWS-mention-the-previous-doc-fixes.patch, #57117
        StatusNone In Progress
        Assigned toNone berny

    Back to the top

    Powered by Savane 3.15-e6e5.
    Corresponding source code