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:

find - search for files in a directory hierarchy
locate - list files in databases that match a pattern
updatedb - update a file name database
xargs - build and execute command lines from standard input

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 http://ftp.gnu.org/pub/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 James Youngman as part of the procedure for uploading to the FTP site. The key that they are signed with is 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. See this message on the Findutils mailing list for a pointer to a keyserver which can cope with such keys (I use subkeys.pgp.net myself).

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 ftp://ftp.gnu.org/gnu/gnu-keyring.gpg.

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.

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 http://mail.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:

If you are a speaker of a language other than English, you could join the Translation Project and help to produce translations of the messages that findutils produces.
Devise and write some new test cases for the findutils test suite.
Select a bug and fix it.
Work on any incomplete tasks on the findutils task list. Before starting work though, send an email to the mailing list to find out if someone else is alredy working on this; if they are, perhaps you could collaborate with them.
Build and test findutils on an unusual platform. This is particularly valuable if you have the time to do this with each new alpha release.

The current maintainer of GNU findutils is James Youngman. 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.

Return to GNU's home page.

Please send FSF & GNU inquiries & questions to gnu@gnu.org. There are also other ways to contact the FSF.

Please send comments on these web pages to webmasters@www.gnu.org, send other questions to gnu@gnu.org. Comments on this specific page should be made to the findutils maintainers at bug-findutils@gnu.org.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.

Updated: $Date: 2005/02/27 22:00:12 $