[bug #62259] find(1) manpage prune example error

[raf]

URL:
  <https://savannah.gnu.org/bugs/?62259>

                 Summary: find(1) manpage prune example error
                 Project: findutils
            Submitted by: raf
            Submitted on: Wed 06 Apr 2022 02:57:55 PM UTC
                Category: documentation
                Severity: 3 - Normal
              Item Group: Wrong result
                  Status: None
                 Privacy: Public
             Assigned to: None
         Originator Name: raf
        Originator Email: 
             Open/Closed: Open
                 Release: 4.9.0
         Discussion Lock: Any
           Fixed Release: None

    _______________________________________________________

Details:

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





    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?62259>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/