Findutils

The GNU Find Utilities are the basic directory searching utilities of the GNU operating system. These programs are typically used in conjunction with other programs to provide modular and powerful directory search and file locating capabilities to other commands.

The tools supplied with this package are:

The find program searches a directory tree to find a file or group of files. It traverses the directory tree and reports all occurrences of a file matching the user's specifications. The find program includes very powerful searching capability.

The locate program scans one or more databases of filenames and displays any matches. This can be used as a very fast find command if the file was present during the last file name database update.

The updatedb program updates the file name database used by the locate program. The file name database contains lists of files that were in particular directory trees when the databases were last updated. This is usually run nightly by the cron system daemon.

The xargs program builds and executes command lines by gathering together arguments it reads on the standard input. Most often, these arguments are lists of file names generated by find.

Documentation

The manual is available in the info system of the GNU Operating System. Use info to access the top level info page. Use info find to access the Find Utilities section directly.

An online version of the documentation is also available, but please note that this is not always fully up-to-date.

Examples

Here is an example operation to make all HTML files in the subdirectory htdocs readable by all using find and xargs. This is a typical example of how find and xargs are used with other utilities to provide powerful directory traversal capability.

find htdocs -name '*.html' -print0 | xargs -0 chmod a+r

See the online info documentation described above for more examples.

Downloading

Released versions of GNU findutils can be found in the subdirectory /gnu/findutils/ on your favorite GNU mirror. For other ways to obtain findutils, please read How to get GNU Software. The latest released version will be the latest version available here at https://ftp.gnu.org/gnu/findutils/.

In between “stable” releases there are also alpha releases which incorporate the newest features or bugfixes, and which are released so that interested parties can test these. The releases are announced on the mailing list, and you should join the mailing list if you plan to test the alpha releases.

Findutils releases are signed by the GNU findutils maintainers as part of the procedure for uploading to the FTP site. The maintainer's keys that they are signed with are available on Savannah. The key is not available from some keyservers because it has an image in a subkey, which some of them don't like.

The GNU project keyring is used to verify all files uploaded to GNU FTP sites. The GNU keyring is itself available on the GNU FTP site; see https://ftp.gnu.org/gnu/gnu-keyring.gpg.

Accessing findutils source code with git

Official releases can be downloaded as source archives as described above, but the findutils source code is also available via git. See the Savannah web page findutils - Git Repositories for details.

How to Get Help

If you would like to report a bug, please do so via the findutils bug reporting page on Savannah. If a bug is reported via the web page, a notification is automatically sent to the <bug-findutils@gnu.org> mailing list. It is not required to submit a bug report via the Savannah bug form, but doing so will prevent the bug from being missed or forgotten and is therefore encouraged. It will also ensure that you are notified when the bug has been fixed.

However, there will be occasions where you're not sure whether the problem you have is actually a bug, or you just want to talk about ideas for improving findutils. Using the mailing list is a good way to do that. You can fill out a form on a web page to join the bug-findutils mailing list or you can send email to <bug-findutils-request@gnu.org> with the word subscribe in the body.

For general discussion of findutils, the <bug-findutils@gnu.org> mailing list is the most appropriate forum. An archive of the findutils bug report mailing list is available at https://lists.gnu.org/archive/html/bug-findutils/. If you have a problem and are not sure it is a bug, or even if you are sure, feel free to open a discussion of the issue on the mailing list. Searching the archive prior to opening a new discussion is recommended as many common problems will have already been discussed and explained.

When reporting problems, please be patient. It may just be that the volunteers are busy. Every message to the bug lists are read by many people. Sometimes there is just nothing to say at the time. If you think your message might not have made it to the list or that you may have missed the response then check the mail archives as described above. If you do not see your message in the archive then we did not see it either. Or perhaps your formatting was such that it was unreadable. A number of posts are unreadable because the text was encoded and it could not be deciphered. If it does not show up as plain text in the archive then it did not get sent to the list in plain text format.

How to Help

To contact the maintainers, either to report a bug or to contribute fixes or improvements, send mail to <bug-findutils@gnu.org>. Please send messages as plain text. If posting patches they should be in unified diff format against the latest cvs testing version available from Savannah if possible or the last alpha test release as the next best version. They should include a text description and the unified diff inline in the message and not attached to it. This makes the messages the most readable to the widest audience and increases the chances of your patches being included in the project.

If you would like to submit a bug report directly to the bug database you may do so on the findutils bug reporting page on Savannah. If a bug is reported via the web page, a notification is automatically sent to the <bug-findutils@gnu.org> mailing list. It is not required to submit a bug report via the Savannah bug form but doing so will prevent the bug from being missed or forgotten and is therefore encouraged.

Some specific ways in which you could help are:

The current maintainers of GNU findutils are James Youngman, Eric Blake, and Bernhard Voelker. A list of previous maintainers and other major contributors is to be found in the AUTHORS file which is included in the findutils source code. A list of other people who have helped is in the file THANKS.