Find
Encyclopedia
In Unix-like
and some other operating system
s,
, locates file
s based on some user
-specified criteria and applies a user-specified action on each matched file. The possible search criteria include a pattern
to match against the file name or a time range to match against the modification time or access time of the file. By default,
.
The related
The three options control how the
At least one path must precede the expression.
internally and commands must be constructed carefully in order to control shell globbing.
Expression elements are whitespace-separated and evaluated from left to right. They can contain logical elements such as AND (-a) and OR (-o) as well as more complex predicates.
The GNU
or soft links
. The POSIX standard
requires that
The
directory that is an ancestor of the last file encountered. When it detects an infinite
loop,
its position in the hierarchy or terminate.
This searches in the current directory (represented by a period) and below it, for files and directories with names starting with my. The 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 directory. In newer versions of the program, the directory may be omitted, and it will imply the current directory.
This limits the results of the above search to only regular files, therefore excluding directories, special files, pipes, symbolic links, etc. my* is enclosed in quotes as otherwise the shell would replace it with the list of files in the current directory starting with my...
find . -name "my*" -type f -ls
This prints extended file information.
This searches every file on the computer for a file with the name myfile and prints it to the screen. It is generally not a good idea to look for data files this way. This can take a considerable amount of time, so it is best to specify the directory more precisely. Some operating systems may mount dynamic filesystems that are not congenial to
This searches every folder on the computer except the subtree excluded_path (pull path including the leading /), for a file with the name myfile. It will not detect directories, devices, links, doors, or other "special" filetypes.
This searches for files named myfile in the /home/weedly directory, the home directory for userid weedly. You should always specify the directory to the deepest level you can remember.
This searches for directories named mydir in the local subdirectory of the current working directory and the /tmp directory.
find / -name "myfile" -type f -print 2>/dev/null
If you are a csh
or tcsh
user, you cannot redirect stderr without redirecting stdout as well. You can use sh to run the
sh -c find / -name "myfile" -type f -print 2>/dev/null
An alternate method when using csh
or tcsh
is to pipe the output from stdout and stderr into a grep
command. This example shows how to suppress lines that contain permission denied errors.
find . -name "myfile" |& grep -v "Permission denied"
The
This command changes the permissions
of all files with a name ending in .mp3 in the directory /var/ftp/mp3. The action is carried out by specifying the option
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
If running under Windows, don't include the backslash before the semicolon:
find . -exec grep blah {} ;
If you will be executing over many results, it is more efficient to pipe the results to the xargs
command instead. xargs is a more modern implementation, and handles long lists in a more intelligent way. The print0 option can be used with this.
The following command will ensure that filenames with whitespaces are passed to the executed COMMAND without being split up by the shell. It looks complicated at first glance, but is widely used.
find . -print0 | xargs -0 COMMAND
The list of files generated by
for more examples and options.
find /tmp -exec grep "search string" '{}' /dev/null \; -print
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. An equivalent mechanism is to use the "-H" or "--with-filename" option to grep:
find /tmp -exec grep -H "search string" '{}' \; -print
GNU grep can be used on its own to perform this task:
grep -r "search string" /tmp
Example of search for "LOG" in jsmith's home directory
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
Example of search for the string "ERROR" in all xml files in the current directory and all sub-directories
find . -name "*.xml" -exec grep "ERROR" '{}' \; -print
The double quotes (" ") surrounding the search string and single quotes (' ' ) surrounding the braces are optional in this example, but needed to allow spaces and other special characters in the string.
If the
find . -name "[mM][yY][fF][iI][lL][eE]*"
This uses Perl
to build the above command for you:
echo "'MyFile*'" |perl -pe 's/([a-zA-Z])/[\L\1\U\1]/g;s/(.*)/find . -name \1/'|sh
find . -size +100k -a -size -500k
This command will search in the /usr/src directory and all sub directories. All files that are of the form '*,v' and '.*,v' are excluded. Important arguments to note are:
-not means the negation of the expression that follows
\( means the start of a complex expression.
\) means the end of a complex expression.
-o means a logical or of a complex expression.
In this case the complex expression is all files like '*,v' or '.*,v'
for file in `find /opt \( -name error_log -o -name 'access_log' -o -name 'ssl_engine_log' -o -name 'rewrite_log' -o
-name 'catalina.out' \) -size +300000k -a -size -5000000k`; do cat /dev/null > $file; done
The units should be one of [bckw], 'b' means 512-byte blocks, 'c' means byte, 'k' means kilobytes and 'w' means 2-byte words. The size does not count indirect blocks, but it does count blocks in sparse files that are not actually allocated.
Unix-like
A Unix-like operating system is one that behaves in a manner similar to a Unix system, while not necessarily conforming to or being certified to any version of the Single UNIX Specification....
and some other operating system
Operating system
An operating system is a set of programs that manage computer hardware resources and provide common services for application software. The operating system is the most important type of system software in a computer system...
s,
find is a command-line utility that searches through one or more directory trees of a file systemFile system
A file system is a means to organize data expected to be retained after a program terminates by providing procedures to store, retrieve and update data, as well as manage the available space on the device which contain it. A file system organizes data in an efficient manner and is tuned to the...
, locates file
Computer file
A computer file is a block of arbitrary information, or resource for storing information, which is available to a computer program and is usually based on some kind of durable storage. A file is durable in the sense that it remains available for programs to use after the current program has finished...
s based on some user
User (computing)
A user is an agent, either a human agent or software agent, who uses a computer or network service. A user often has a user account and is identified by a username , screen name , nickname , or handle, which is derived from the identical Citizen's Band radio term.Users are...
-specified criteria and applies a user-specified action on each matched file. The possible search criteria include a pattern
Pattern matching
In computer science, pattern matching is the act of checking some sequence of tokens for the presence of the constituents of some pattern. In contrast to pattern recognition, the match usually has to be exact. The patterns generally have the form of either sequences or tree structures...
to match against the file name or a time range to match against the modification time or access time of the file. By default,
find returns a list of all files below the current working directoryWorking directory
In computing, the working directory of a process is a directory of a hierarchical file system, if any, dynamically associated with each process. When the process refers to a file using a simple file name or relative path , the reference is interpreted relative to the current working directory of...
.
The related
locateGNU locatelocate is a Unix utility first created in 1983 used to find files on filesystems. It searches through a prebuilt database of files generated by updatedb or a daemon and compressed using incremental encoding...
programs use a database of indexed files obtained through find (updated at regular intervals, typically by cronCronCron is a time-based job scheduler in Unix-like computer operating systems. Cron enables users to schedule jobs to run periodically at certain times or dates...
job) to provide a faster method of searching the entire filesystem for files by name. This sacrifices overall efficiency (because filesystems are regularly interrogated even when no users needs information) and absolute accuracy (since the database is not updated in real time) for significant speed improvements (particularly on very large filesystems). On fast systems with small drives, locate is not necessary nor desirable.Find syntax
find [-H] [-L] [-P] path... [expression]The three options control how the
find command should treat symbolic links. The default behaviour is never to follow symbolic links. This can be explicitly specified using the -P flag. The -L flag will cause the find command to follow symbolic links. The -H flag will only follow symbolic links while processing the command line arguments. These flags are not available with some older versions of find.At least one path must precede the expression.
find is capable of interpreting wildcardsWildcard character
-Telecommunication:In telecommunications, a wildcard character is a character that may be substituted for any of a defined subset of all possible characters....
internally and commands must be constructed carefully in order to control shell globbing.
Expression elements are whitespace-separated and evaluated from left to right. They can contain logical elements such as AND (-a) and OR (-o) as well as more complex predicates.
The GNU
find has a large number of additional features not specified by POSIX.POSIX protection from infinite output
Real-world filesystems often contain looped structures created through the use of hardHard link
In computing, a hard link is a directory entry that associates a name with a file on a file system. . The term is used in file systems which allow multiple hard links to be created for the same file. This has the effect of creating multiple names for the same file, causing an aliasing effect: e.g...
or soft links
Symbolic link
In computing, a symbolic link is a special type of file that contains a reference to another file or directory in the form of an absolute or relative path and that affects pathname resolution. Symbolic links were already present by 1978 in mini-computer operating systems from DEC and Data...
. The POSIX standard
POSIX
POSIX , an acronym for "Portable Operating System Interface", is a family of standards specified by the IEEE for maintaining compatibility between operating systems...
requires that
The
find utility shall detect infinite loops; that is, entering a previously visiteddirectory that is an ancestor of the last file encountered. When it detects an infinite
loop,
find shall write a diagnostic message to standard error and shall either recoverits position in the hierarchy or terminate.
From current directory
find . -name 'my*'This searches in the current directory (represented by a period) and below it, for files and directories with names starting with my. The quotes avoid the shell
Shell (computing)
A shell is a piece of software that provides an interface for users of an operating system which provides access to the services of a kernel. However, the term is also applied very loosely to applications and may include any software that is "built around" a particular component, such as web...
expansion — without them the shell would replace my* with the list of files whose names begin with my in the current directory. In newer versions of the program, the directory may be omitted, and it will imply the current directory.
Files only
find . -name "my*" -type fThis limits the results of the above search to only regular files, therefore excluding directories, special files, pipes, symbolic links, etc. my* is enclosed in quotes as otherwise the shell would replace it with the list of files in the current directory starting with my...
Commands
The previous examples created listings of results because, by default,find executes the '-print' action. (Note that early versions of the find command had no default action at all; therefore the resulting list of files would be discarded, to the bewilderment of users.)find . -name "my*" -type f -ls
This prints extended file information.
Search all directories
find / -type f -name "myfile" -printThis searches every file on the computer for a file with the name myfile and prints it to the screen. It is generally not a good idea to look for data files this way. This can take a considerable amount of time, so it is best to specify the directory more precisely. Some operating systems may mount dynamic filesystems that are not congenial to
find.Search all but one directory subtree
find / -path excluded_path -prune -o -type f -name myfile -printThis searches every folder on the computer except the subtree excluded_path (pull path including the leading /), for a file with the name myfile. It will not detect directories, devices, links, doors, or other "special" filetypes.
Specify a directory
find /home/weedly -name "myfile" -type f -printThis searches for files named myfile in the /home/weedly directory, the home directory for userid weedly. You should always specify the directory to the deepest level you can remember.
Search several directories
find local /tmp -name mydir -type d -printThis searches for directories named mydir in the local subdirectory of the current working directory and the /tmp directory.
Ignore errors
If you're doing this as a user other than root, you might want to ignore permission denied (and any other) errors. Since errors are printed to stderr, they can be suppressed by redirecting the output to /dev/null. The following example shows how to do this in the bash shell:find / -name "myfile" -type f -print 2>/dev/null
If you are a csh
C shell
The C shell is a Unix shell that was created by Bill Joy while a graduate student at University of California, Berkeley in the late 1970s. It has been distributed widely, beginning with the 2BSD release of the BSD Unix system that Joy began distributing in 1978...
or tcsh
Tcsh
tcsh is a Unix shell based on and compatible with the C shell . It is essentially the C shell with programmable command line completion, command-line editing, and a few other features.-History:...
user, you cannot redirect stderr without redirecting stdout as well. You can use sh to run the
find command to get around this:sh -c find / -name "myfile" -type f -print 2>/dev/null
An alternate method when using csh
C shell
The C shell is a Unix shell that was created by Bill Joy while a graduate student at University of California, Berkeley in the late 1970s. It has been distributed widely, beginning with the 2BSD release of the BSD Unix system that Joy began distributing in 1978...
or tcsh
Tcsh
tcsh is a Unix shell based on and compatible with the C shell . It is essentially the C shell with programmable command line completion, command-line editing, and a few other features.-History:...
is to pipe the output from stdout and stderr into a grep
Grep
grep is a command-line text-search utility originally written for Unix. The name comes from the ed command g/re/p...
command. This example shows how to suppress lines that contain permission denied errors.
find . -name "myfile" |& grep -v "Permission denied"
Find any one of differently named files
find . \( -name "*jsp" -o -name "*java" \) -type f -lsThe
-ls option prints extended information, and the example finds any file whose name ends with either 'jsp' or 'java'. Note that the parentheses are required. Also note that the operator "or" can be abbreviated as "o". The "and" operator is assumed where no operator is given. In many shells the parentheses must be escaped with a backslash, "\(" and "\)", to prevent them from being interpreted as special shell characters. The -ls option and the -or operator are not available on all versions of find.Execute an action
find /var/ftp/mp3 -name "*.mp3" -type f -exec chmod 644 {} \;This command changes the permissions
File system permissions
Most current file systems have methods of administering permissions or access rights to specific users and groups of users. These systems control the ability of the users to view or make changes to the contents of the filesystem....
of all files with a name ending in .mp3 in the directory /var/ftp/mp3. The action is carried out by specifying the option
-exec chmodChmodThe chmod command is a Unix command that lets a user tell the system how much access it should permit to a file. It changes the file system modes of files and directories. The modes include permissions and special modes...
644 {} \; in the command. For every 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.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 running under Windows, don't include the backslash before the semicolon:
find . -exec grep blah {} ;
If you will be executing over many results, it is more efficient to pipe the results to the xargs
Xargs
xargs is a command on Unix and most Unix-like operating systems used to build and execute command lines from standard input. Under the Linux kernel before version 2.6.23, arbitrarily long lists of parameters could not be passed to a command, so xargs breaks the list of arguments into sublists small...
command instead. xargs is a more modern implementation, and handles long lists in a more intelligent way. The print0 option can be used with this.
The following command will ensure that filenames with whitespaces are passed to the executed COMMAND without being split up by the shell. It looks complicated at first glance, but is widely used.
find . -print0 | xargs -0 COMMAND
The list of files generated by
find (whilst it is being generated) is simultaneously piped to xargs, which then executes COMMAND with the files as arguments. See xargsXargs
xargs is a command on Unix and most Unix-like operating systems used to build and execute command lines from standard input. Under the Linux kernel before version 2.6.23, arbitrarily long lists of parameters could not be passed to a command, so xargs breaks the list of arguments into sublists small...
for more examples and options.
Search for a string
This command will search for a string in all files from the /tmp directory and below:find /tmp -exec grep "search string" '{}' /dev/null \; -print
The /dev/null
/dev/null
In Unix-like operating systems, /dev/null or the null device is a special file that discards all data written to it and provides no data to any process that reads from it ....
argument is used to show the name of the file before the text that is found. Without it, only the text found is printed. An equivalent mechanism is to use the "-H" or "--with-filename" option to grep:
find /tmp -exec grep -H "search string" '{}' \; -print
GNU grep can be used on its own to perform this task:
grep -r "search string" /tmp
Example of search for "LOG" in jsmith's home directory
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
Example of search for the string "ERROR" in all xml files in the current directory and all sub-directories
find . -name "*.xml" -exec grep "ERROR" '{}' \; -print
The double quotes (" ") surrounding the search string and single quotes (
Search in case insensitive mode
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]*"
This uses Perl
Perl
Perl is a high-level, general-purpose, interpreted, dynamic programming language. Perl was originally developed by Larry Wall in 1987 as a general-purpose Unix scripting language to make report processing easier. Since then, it has undergone many changes and revisions and become widely popular...
to build the above command for you:
echo "'MyFile*'" |perl -pe 's/([a-zA-Z])/[\L\1\U\1]/g;s/(.*)/find . -name \1/'|sh
Search files by size
Example of searching files with size between 100 kilobytes and 500 kilobytes.find . -size +100k -a -size -500k
Search files by name and size
find /usr/src -not \( -name "*,v" -o -name ".*,v" \) '{}' \; -printThis command will search in the /usr/src directory and all sub directories. All files that are of the form '*,v' and '.*,v' are excluded. Important arguments to note are:
-not means the negation of the expression that follows
\( means the start of a complex expression.
\) means the end of a complex expression.
-o means a logical or of a complex expression.
In this case the complex expression is all files like '*,v' or '.*,v'
for file in `find /opt \( -name error_log -o -name 'access_log' -o -name 'ssl_engine_log' -o -name 'rewrite_log' -o
-name 'catalina.out' \) -size +300000k -a -size -5000000k`; do cat /dev/null > $file; done
The units should be one of [bckw], 'b' means 512-byte blocks, 'c' means byte, 'k' means kilobytes and 'w' means 2-byte words. The size does not count indirect blocks, but it does count blocks in sparse files that are not actually allocated.
See also
- GNU locateGNU locatelocate is a Unix utility first created in 1983 used to find files on filesystems. It searches through a prebuilt database of files generated by updatedb or a daemon and compressed using incremental encoding...
, a Unix search tool based on a prebuilt database therefore faster and less accurate thanfind - mdfind, a similar utility that utilizes metadata for Mac OS XMac OS XMac OS X is a series of Unix-based operating systems and graphical user interfaces developed, marketed, and sold by Apple Inc. Since 2002, has been included with all new Macintosh computer systems...
and DarwinDarwin (operating system)Darwin is an open source POSIX-compliant computer operating system released by Apple Inc. in 2000. It is composed of code developed by Apple, as well as code derived from NeXTSTEP, BSD, and other free software projects.... - List of Unix programs
- List of DOS commands
- find (command)Find (command)In computing, find is a command in the command line interpreters of DOS, OS/2 and Microsoft Windows. It is used to search for a specific text string in a file or files...
, a DOS and Windows command that is very different from UNIXfind - findutilsFindutilsFindutils is a GNU package which offers basic file searching utilities to search the systems directories of GNU and Unix based computers. It contains implementations of the tools find, locate, updatedb, and xargs....
- treeTree (Unix)Tree is a program available for Unix and Unix-like systems. tree is a recursive directory listing program that produces a depth-indented listing of files....
External links
- A story on the origins of the Unix find command.
- GNU Findutils - Comes with the xargsXargsxargs is a command on Unix and most Unix-like operating systems used to build and execute command lines from standard input. Under the Linux kernel before version 2.6.23, arbitrarily long lists of parameters could not be passed to a command, so xargs breaks the list of arguments into sublists small...
and locateGNU locatelocate is a Unix utility first created in 1983 used to find files on filesystems. It searches through a prebuilt database of files generated by updatedb or a daemon and compressed using incremental encoding...
commands. - Official webpage for GNU find
- Softpanorama find tutorial
- Exercises "Find"
- "Find helper" - unix "find" wizard
- Guide to Linux Find Command Mastery
- Top 'find' commands - interesting usage