Introduction

This manual shows how to find files that meet criteria you specify, and how to perform various actions on the files that you find. The principal programs that you use to perform these tasks are find, locate, and xargs. Some of the examples in this manual use capabilities specific to the GNU versions of those programs.

GNU find was originally written by Eric Decker, with enhancements by David MacKenzie, Jay Plett, and Tim Wood. GNU xargs was originally written by Mike Rendell, with enhancements by David MacKenzie. GNU locate and its associated utilities were originally written by James Woods, with enhancements by David MacKenzie. The idea for `find -print0' and `xargs -0' came from Dan Bernstein. Many other people have contributed bug fixes, small improvements, and helpful suggestions. Thanks!

Mail suggestions and bug reports for these programs to bug-gnu-utils@prep.ai.mit.edu. Please include the version number, which you can get by running `find --version'.

• Scope
• Overview
• find Expressions

Scope

For brevity, the word file in this manual means a regular file, a directory, a symbolic link, or any other kind of node that has a directory entry. A directory entry is also called a file name. A file name may contain some, all, or none of the directories in a path that leads to the file. These are all examples of what this manual calls "file names":

parser.c
README
./budget/may-94.sc
fred/.cshrc
/usr/local/include/termcap.h

A directory tree is a directory and the files it contains, all of its subdirectories and the files they contain, etc. It can also be a single non-directory file.

These programs enable you to find the files in one or more directory trees that:

• have names that contain certain text or match a certain pattern;
• are links to certain files;
• were last used during a certain period of time;
• are within a certain size range;
• are of a certain type (regular file, directory, symbolic link, etc.);
• are owned by a certain user or group;
• have certain access permissions;
• contain text that matches a certain pattern;
• are within a certain depth in the directory tree;
• or some combination of the above.

Once you have found the files you're looking for (or files that are potentially the ones you're looking for), you can do more to them than simply list their names. You can get any combination of the files' attributes, or process the files in many ways, either individually or in groups of various sizes. Actions that you might want to perform on the files you have found include, but are not limited to:

• view or edit
• store in an archive
• remove or rename
• change access permissions
• classify into groups

This manual describes how to perform each of those tasks, and more.

Overview

The principal programs used for making lists of files that match given criteria and running commands on them are find, locate, and xargs. An additional command, updatedb, is used by system administrators to create databases for locate to use.

find searches for files in a directory hierarchy and prints information about the files it found. It is run like this:

find [file...] [expression]

Here is a typical use of find. This example prints the names of all files in the directory tree rooted in `/usr/src' whose name ends with `.c' and that are larger than 100 Kilobytes.

find /usr/src -name '*.c' -size +100k -print

locate searches special file name databases for file names that match patterns. The system administrator runs the updatedb program to create the databases. locate is run like this:

locate [option...] pattern...

This example prints the names of all files in the default file name database whose name ends with `Makefile' or `makefile'. Which file names are stored in the database depends on how the system administrator ran updatedb.

locate '*[Mm]akefile'

The name xargs, pronounced EX-args, means "combine arguments." xargs 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. xargs is run like this:

xargs [option...] [command [initial-arguments]]

The following command searches the files listed in the file `file-list' and prints all of the lines in them that contain the word `typedef'.

xargs grep typedef < file-list

find Expressions

The expression that find uses to select files consists of one or more primaries, each of which is a separate command line argument to find. find evaluates the expression each time it processes a file. An expression can contain any of the following types of primaries:

options

affect overall operation rather than the processing of a specific file;

tests

return a true or false value, depending on the file's attributes;

actions

have side effects and return a true or false value; and

operators

connect the other arguments and affect when and whether they are evaluated.

You can omit the operator between two primaries; it defaults to `-and'. See section Combining Primaries With Operators, for ways to connect primaries into more complex expressions. If the expression contains no actions other than `-prune', `-print' is performed on all files for which the entire expression is true (see section Print File Name).

Options take effect immediately, rather than being evaluated for each file when their place in the expression is reached. Therefore, for clarity, it is best to place them at the beginning of the expression.

Many of the primaries take arguments, which immediately follow them in the next command line argument to find. Some arguments are file names, patterns, or other strings; others are numbers. Numeric arguments can be specified as

+n

for greater than n,

-n

for less than n,

n

for exactly n.