find is a shellcommand that locates files[1] based on search criteria and performs actions on the matching files such as printing the file systempath to standard output. It starts searching at a root directory of a hierarchical structure and recursively traverses the tree although can be limited to a maximum number of levels. Commonly used search criteria include file namepattern matching and time range matching for last modification or last access. With no arguments, the command outputs the path of each file in the tree rooted at the working directory. The command can search through different file systems of partitions belonging to one or more storage devices mounted under the starting directory.[2] The command is available on most Unix-like systems.
The command first appeared in Version 5 Unix as part of the Programmer's Workbench project, and was written by Dick Haight alongside cpio,[3] which were designed to be used together.[4]
The GNU implementation was originally written by Eric Decker. It was later enhanced by David MacKenzie, Jay Plett, and Tim Wood.[5]
The command was ported to the IBM i operating system.[6]
The BusyBoxcomputer program provides the find command and many other commands in a single executable file.
Use
The syntax of the command can be described as:
$ find [-H|-L] path... [expression]
Traditionally, at least one path must precede the expression but newer versions allow for no path argument; defaulting to the working directory.
The expression can specify various aspects including match criteria and actions to perform on matched files. Expression elements are separated by whitespace and are evaluated left-to-right. The command can match via wildcard characters but wildcard match text must be quoted to prevent shell globbing. If the expression is omitted, then all files are matched.
The GNU implementation has features beyond the POSIX specification.
Expression
The expression specifies the behavior of the command including what files to select (sometimes called predicate) and what to do with each matching file (sometimes called action). The elements of an expression commonly include:
-name pattern
Selects files with a name that matches a shell-glob pattern.
Prints the name of the found file plus a newline to stdout. If the expression does not contain an action option (such as -print0, -exec, or -ok) the action of -print is performed.
-print0
Prints the name of the found file plus a null character to the stdout. Not required by POSIX.
-exec program [argument...];
Runs a program with arguments for each candidate file; selecting files for which the program results in exit status 0. If program or an argument is {}, it is replaced with the candidate path. POSIX doesn't specify what happens if multiple {} are specified. Most implementations replace each {} with the candidate path.
-exec program [argument...] {} +
Runs a program with arguments followed by as many candidate paths as possible. Multiple commands are run if the maximum command-line size is exceeded, like for xargs).[7]
-ok program [argument...];
For each candidate path, prompts the user for confirmation. If the user confirms (typically by entering y or yes), it behaves like -exec program [arguments...];, otherwise the command is not run for the candidate path and the file is not selected.
-maxdepth
Limits the directory depth to search. For example, -maxdepth 2 limits searching to the root directory and its direct children.
Operators
Operators are used to combine expressions elements. Operators are listed in order of decreasing precedence:
Precedence
( expr ); Selects evaluation order of subexpression.
Negation
! expr; true if expr is false.
Logical and
expr1 expr2 or expr1 -a expr2; expr2 is not evaluated if expr1 is false.
Logical or
expr1 -o expr2; expr2 is not evaluated if expr1 is true.
The following command searches the current working directory tree for files named A or B.
$ find.-nameA-o-nameB
The following command searches the current working directory tree except the subdirectory tree ".svn" for files named "foo.cpp". Operator ! is quoted so that it's not interpreted as the history substitution character.
$ find.-name'foo.cpp''!'-path'.svn'
Symbolic link traversal
In light of the fact that a file system can contain looped structures via hard and soft links, POSIX requires that the command detect infinite loops; that is, entering a previously visited directory that is an ancestor of the last file encountered. When it detects an infinite loop, the command must write a diagnostic message to standard error plus either recover its position in the hierarchy or terminate.
The -H and -L options, specified in the POSIX standard, control how the command handles symbolic links. The default behavior is to not follow symbolic links. The -L option causes the command to follow symbolic links. The -H option causes the command to follow symbolic links while processing the command line arguments.[7] A common extension is the -P option, for explicitly disabling symlink following.[8][9]
Examples
By name
The following command searches the current working directory tree for files named starting with my. The single quotes avoid the shell expansion. Without them, the shell would replace my* with the list of files whose names begin with my in the current working directory which is not necessarily the same as the files matching in subdirectories.
$ find.-name'my*'
Limit by file type
The following command includes -type f to limit results to regular files; excluding other file system items such as directories and symbolic links.
$ find.-typef
Include file detail
The following command includes the -ls action option to include detailed file information like from command ls -a.
$ find.-ls
Exclude subdirectory tree
The following command searches every directory except the subdirectory tree excluded_path (full path including the leading /) that is pruned by the -prune action, for a regular file whose name is myfile.
The following command searches the /home/weedly directory tree for regular files named myfile. You should always specify the directory to the deepest level you can remember.
$ find/home/weedly-namemyfile-typef-print
Search multiple directories
The following command searches the local subdirectory tree of the current working directory and the /tmp directory tree for directories named mydir.
$ findlocal/tmp-namemydir-typed-print
Find any one of differently named files
The -ls operator prints extended information, and the example finds any regular file whose name ends with either 'jsp' or 'java'. Note that the parentheses are required. In many shells the parentheses must be escaped with a backslash (\( and \)) to prevent them from being interpreted as special shell characters. The -ls operator is not available on all versions of find.
$ find.\(-name'*jsp'-o-name'*java'\)-typef-ls
Execute an action
The following command changes the permissions of all regular files whose names end with .mp3 in the directory tree /var/ftp/mp3. The action is carried out by specifying the statement -exec chmod 644 {} \; in the command. For every regular file whose name ends in .mp3, the command chmod 644 {} is executed replacing {} with the name of the file. The semicolon (backslashed to avoid the shell interpreting it as a command separator) indicates the end of the command. Permission 644, usually shown as rw-r--r--, gives the file owner full permission to read and write the file, while other users have read-only access. In some shells, the {} must be quoted. The trailing ";" is customarily quoted with a leading "\", but could just as effectively be enclosed in single quotes.
Note that the command itself should not be quoted; otherwise you get error messages like
find: echo "mv ./3bfn rel071204": No such file or directory
which means that find is trying to run a file called 'echo"mv ./3bfn rel071204"' and failing.
If you will be executing over many results, it is more efficient to use a variant of the exec primary that collects file names up to ARG_MAX and then executes COMMAND with a list of file names.
$ find.-execCOMMAND{}+
This will ensure that file names with whitespaces are passed to the executed COMMAND without being split up by the shell.
Delete files and directories
The -delete action is a GNU extension, and using it turns on -depth. So, if you are testing a find command with -print instead of -delete in order to figure out what will happen before going for it, you need to use -depth -print.
Delete empty files and print the names (note that -empty is a vendor unique extension from GNU find that may not be available in all find implementations):
$ find.-empty-delete-print
Delete empty regular files:
$ find.-typef-empty-delete
Delete empty directories:
$ find.-typed-empty-delete
Delete empty files named 'bad':
$ find.-namebad-empty-delete
To prevent deleting all files, the -delete option should only be used with selection options such as -empty or -name. The following command deletes all files a directory tree.
$ find.-delete
Search for a string
The following command searches for files in the /tmp directory tree for a string:
The /dev/null argument is used to show the name of the file before the text that is found. Without it, only the text found is printed. (Alternatively, some versions of grep support a -H flag that forces the file name to be printed.) GNU grep can be used on its own to perform this task:
$ grep-r'search string'/tmp
The following command searches for "LOG" in jsmith's home directory tree.
The double quotes (") surrounding the search string and single quotes (') surrounding the braces are optional in this example, but needed to allow spaces and some other special characters in the string. Note with more complex text (notably in most popular shells descended from `sh` and `csh`) single quotes are often the easier choice, since double quotes do not prevent all special interpretation. Quoting file names which have English contractions demonstrates how this can get rather complicated, since a string with an apostrophe in it is easier to protect with double quotes:
A command on Microsoft-based systems that recursively lists files of a directory tree; indenting the file names according to their position in the file hierarchy.
walk and sor
Commands on Plan 9 from Bell Labs systems that provide similar functionality as find. walk finds files in a directory tree and prints the names and sor filters (like grep) by evaluating expressions in the form of a shell script. The commands are not part of Plan 9 from User Space, so Google's Benjamin Barenblat has a ported version to POSIX systems available through GitHub.[10]
A tool that searches a prebuilt database instead of the file system. The performance of locate can exceed that of find, but results can be inaccurate if the database is out-of-date. Typically, the database is updated from file system information via a find command run periodically by a cron job.
This page is based on this Wikipedia article Text is available under the CC BY-SA 4.0 license; additional terms may apply. Images, videos and audio are available under their respective licenses.
