Find (Unix)

Last updated
find
Original author Dick Haight
Developer AT&T Bell Laboratories
Operating system Unix, Unix-like, Plan 9, IBM i
Platform Cross-platform
Type Command

find is a shell command that locates files [a] based on search criteria and performs actions on the matching files such as printing the file system path to the standard output. It starts searching at a directory in 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, file type 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. [1] The command is available on most Unix-like systems.

Contents

Variants

The command first appeared in Version 5 Unix as part of the Programmer's Workbench project, and was written by Dick Haight alongside cpio, [2] which were designed to be used together. [3]

The GNU implementation was originally written by Eric Decker. It was later enhanced by David MacKenzie, Jay Plett, and Tim Wood. [4] The GNU implementation provides features beyond the POSIX specification.

The command was ported to the IBM i operating system. [5]

The BusyBox computer 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.

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.
-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 the standard output. 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 standard output. 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). [6]
-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.
-mtime, -ctime, -atime
Modification time, inode change time and access time, respectively. Selects files with time metadata matching a number of days ago. With a + prefix, the number specifies at least and with a - prefix, the number specifies less than.
-daystart
Measure time from the beginning of a day rather than the last 24 hours.
-newer [file], -cnewer [file], -anewer [file]
Selects files more recently modified than a file. These support a -not prefix for inverse results or range.
-newermt YYYY-MM-DD
Selects files with last modified after date. Also supports a -not prefix for modified before date.

Operators

Operators are used to combine expression 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.

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. [6] A common extension is the -P option, for explicitly disabling symlink following. [7] [8]

Examples

Search by wildcard

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 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 /not/this/one as specified by the -prune option, for a regular file named myfile.

$ find/-path/not/this/one-prune-o-typef-namemyfile-print

Search multiple directories

The following command searches the dira and dirb subdirectory trees for files named myf.

$ finddiradirb-namemyf

Find any one of differently named files

This following command finds files with a name ending with either "jsp" or "java" by combining two -name options with an -o option. The sub-expression (-name '*jsp' -o -name '*java') is enclosed in parentheses which are each escaped with a backslash to prevent them from being interpreted as special shell characters.

$ find.\(-name'*jsp'-o-name'*java'\)

Execute a program

The following command changes the permissions of all files with names matching "*.mp3" in the directory tree "/var/ftp/mp3". The action is specified by -exec chmod 644 {} \;. For every matching file, the command chmod 644 {} is executed by {} replaced with the name of the file. The semicolon (with backslash prefix to avoid the shell interpreting it as a command separator) indicates the end of the command. In some shells, the {} must be quoted. The trailing ; is often escaped with a leading \, but can be enclosed in single quotes instead.

$ find/var/ftp/mp3-name'*.mp3'-typef-execchmod644{}\;

Delete files

The following command deletes empty files and print the names. The -delete option is an extension, originally added in some BSD-family operating systems, [9] and present in FreeBSD 2.2.1 and later, [10] NetBSD 5.0 and later, [11] OpenBSD 6.1 and later, [12] DragonFly BSD [13] GNU find, [14] and macOS. [15] 

$ find.-empty-delete-print

Search by owner

The following command searches file owned by user 123.

$ find.-user123

Ignore case

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

Search by size

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

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

Search by time

The following command searches for files in the document folder modified in the last week.

$ find~/Documents/-mtime-7

The following command finds files last edited in February 2017.

$ find~/Documents/-newermt2017-02-01-not-newermt2017-03-01

The following command lists files edited more recently than "document.txt".

$ find~/Documents/-newerdocument.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. [16]
fd
An alternative to find written in Rust. [17]
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.

See also

Notes

  1. ↑ Per normal Unix terminology, a file is a file system entry; which can be of any Unix file type including normal file, directory or other more-specialized types.

References

  1. ↑ "find(1) – Linux manual page". man7.org. Retrieved 2019-11-19.
  2. ↑ McIlroy, M. D. (1987). A Research Unix reader: annotated excerpts from the Programmer's Manual, 1971–1986 (PDF) (Technical report). CSTR. Bell Labs. 139.
  3. ↑ "libarchive/libarchive". GitHub. Retrieved 2015-10-04.
  4. ↑ Finding Files
  5. ↑ "IBM System i Version 7.2 Programming Qshell" (PDF). IBM . Retrieved 2020-09-05.
  6. 1 2 find : find files – Shell and Utilities Reference, The Single UNIX Specification , Version 5 from The Open Group
  7. ↑ find(1)  –  FreeBSD General Commands Manual
  8. ↑ find(1)  –  Linux User Manual – User Commands from Manned.org
  9. ↑ "10.1.6 Using the -delete action". GNU Findutils.
  10. ↑ "FreeBSD 2.2.1 find(1)". April 1, 1994.
  11. ↑ "NetBSD 5.0 find(1)". July 19, 2007.
  12. ↑ "OpenBSD 6.1 find(1)". January 3, 2017.
  13. ↑ "DragonFly BSD find(1)".
  14. ↑ "3.4 Delete Files". GNU Findutils.
  15. ↑ "macOS find(1)". -delete.
  16. ↑ "google / walk: Plan 9 style utilities to replace find(1)". GitHub. Retrieved 30 March 2020.
  17. ↑ Peter, David (30 March 2020). "sharkdp/fd: A simple, fast and user-friendly alternative to 'find'". GitHub.
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.