find (Unix)

This article needs additional citations for verification. Please help improve this article by adding citations to reliable sources. Unsourced material may be challenged and removed. Find sources: "Find" Unix – news · newspapers · books · scholar · JSTOR (June 2016) (Learn how and when to remove this message)

find is a shell command that locates files^[1] based on search criteria and performs actions on the matching files such as printing the file system path 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 name pattern 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 BusyBox computer program provides the find command and many other commands in a single executable file.

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.

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.

-type type

Selects files that are a specific Unix file type:

b: block device (buffered)

c: character device (unbuffered)

d: directory

f: regular file

l: symbolic link

p: named pipe

s: socket

D: door

-print

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 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 . -name A -o -name B

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'

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]

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*'

The following command includes -type f to limit results to regular files; excluding other file system items such as directories and symbolic links.

$ find . -type f

The following command includes the -ls action option to include detailed file information like from command ls -a.

$ find . -ls

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.

$ find / -path excluded_path -prune -o -type f -name myfile -print

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 -name myfile -type f -print

The following command searches the local subdirectory tree of the current working directory and the /tmp directory tree for directories named mydir.

$ find local /tmp -name mydir -type d -print

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' \) -type f -ls

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.

$ find /var/ftp/mp3 -name '*.mp3' -type f -exec chmod 644 {} \;

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 . -exec COMMAND {} +

This will ensure that file names with whitespaces are passed to the executed COMMAND without being split up by the shell.

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 . -type f -empty -delete

Delete empty directories:

$ find . -type d -empty -delete

Delete empty files named 'bad':

$ find . -name bad -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

The following command searches for files in the /tmp directory tree for a string:

$ find /tmp -type f -exec grep 'search string' /dev/null '{}' \+

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.

$ find ~jsmith -exec grep LOG '{}' /dev/null \; -print
/home/jsmith/scripts/errpt.sh:cp $LOG $FIXEDLOGNAME
/home/jsmith/scripts/errpt.sh:cat $LOG
/home/jsmith/scripts/title:USER=$LOGNAME

The following commands searches for the string "ERROR" in all XML files in the current working directory tree:

$ find . -name "*.xml" -exec grep "ERROR" /dev/null '{}' \+

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:

$ find . -name "file-containing-can't" -exec grep "can't" '{}' \; -print

$ find . -user <userid>

The following command matches file names ignoring case. The -iname option is not POSIX required.

$ find . -iname 'MyFile*'

If the -iname switch is not supported on your system then workaround techniques may be possible such as:

$ find . -name '[mM][yY][fF][iI][lL][eE]*'

The following command searches for files sized between 100 kilobytes and 500 kilobytes.

$ find . -size +100k -a -size -500k

Date ranges can be used to, for example, list files changed since a backup.

• -mtime : modification time
• -ctime : inode change time
• -atime : access time

Files modified a relative number of days ago:

• +[number] = At least this many days ago.
• -[number] = Less than so many days ago.
• [number] = Exactly this many days ago.
• Optionally add -daystart to measure time from the beginning of a day (0 o'clock) rather than the last 24 hours.

The following command searches for text files in the document folder modified since one week.

$ find ~/Documents/ -iname "*.txt" -mtime -7

Files modified before or after an absolute date and time:

• -newermt YYYY-MM-DD: Last modified after date
• -not -newermt YYYY-MM-DD: Last modified before date

Example to find all text files last edited in February 2017:

$ find ~/Documents/ -iname "*.txt"  -newermt 2017-02-01 -not -newermt 2017-03-01

• -newer [file]: More recently modified than specified file.
  • -cnewer: Same with inode change time.
  • -anewer: Same with access time.
  • Also prependable with -not for inverse results or range.

List all text files edited more recently than "document.txt":

$ find ~/Documents/ -iname "*.txt"  -newer document.txt

grep

A command for searching plain-text for lines matching a regular expression.

find

A command on Microsoft-based systems that although has the same name, provides significantly different functionality than the Unix-based command.

dir

A commonly-used command for listing files on Microsoft-based systems. It provides the /s option to recursively search for files or directories.

tree

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]

fd

An alternative to find written in Rust.^[11]

locate

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.

• Filter (higher-order function) – Computer programming function
• find (Windows) – CommandPages displaying short descriptions with no spaces
• forfiles – Windows command that finds files by attribute, similar to Unix find
• grep – Unix command line utility for text search
• List of POSIX commands
• List of DOS commands
• Spotlight (Apple) – macOS search feature

The Wikibook Guide to Unix has a page on the topic of: Commands

• Official webpage for GNU find
• Command find – 25 practical examples