man > find(1)

man perldoc info pydoc3 ri search

📖 NAME

find - search for files in a directory hierarchy

🚀 Quick Reference

Use Case	Command	Description
🔍 Find file by name	find . -name "*.txt"	Search for files matching pattern in current directory
🗑️ Delete found files	find . -name "*.tmp" -delete	Delete all matching files (use with caution)
📄 Execute command on each file	find . -type f -exec file {} \;	Run file command on each regular file
⏰ Find files modified in last 24h	find . -mtime 0	Files modified less than 24 hours ago
🔒 Find files by permission	find . -perm 644	Files with exact permissions 644
📂 Find directories only	find . -type d	List all directories
🔗 Follow symbolic links	find -L . -name "*.conf"	Follow symlinks while searching
🛑 Prune directory	find . -path ./node_modules -prune -o -print	Skip node_modules directory
📏 Find files larger than 100MB	find . -size +100M	Files larger than 100 megabytes
🔗 Find broken symlinks	find . -xtype l	Find symbolic links pointing to non-existent files

📋 SYNOPSIS

find [-H] [-L] [-P] [-D debugopts] [-Olevel] [starting-point...] [expression]

📝 DESCRIPTION

This manual page documents the GNU version of find. GNU find searches the directory tree rooted at each given starting-point by evaluating the given expression from left to right, according to the rules of precedence (see section OPERATORS), until the outcome is known (the left hand side is false for and operations, true for or), at which point find moves on to the next file name. If no starting-point is specified, . is assumed.

If you are using find in an environment where security is important (for example if you are using it to search directories that are writable by other users), you should read the Security Considerations chapter of the findutils documentation, which is called Finding Files and comes with findutils. That document also includes a lot more detail and discussion than this manual page, so you may find it a more useful source of information.

⚙️ OPTIONS

The -H, -L and -P options control the treatment of symbolic links. Command-line arguments following these are taken to be names of files or directories to be examined, up to the first argument that begins with -, or the argument ( or !. That argument and any following arguments are taken to be the expression describing what is to be searched for. If no paths are given, the current directory is used. If no expression is given, the expression -print is used (but you should probably consider using -print0 instead, anyway).

This manual page talks about 'options' within the expression list. These options control the behaviour of find but are specified immediately after the last path name. The five 'real' options -H, -L, -P, -D and -O must appear before the first path name, if at all. A double dash -- could theoretically be used to signal that any remaining arguments are not options, but this does not really work due to the way find determines the end of the following path arguments: it does that by reading until an expression argument comes (which also starts with a -). Now, if a path argument would start with a -, then find would treat it as expression argument instead. Thus, to ensure that all start points are taken as such, and especially to prevent that wildcard patterns expanded by the calling shell are not mistakenly treated as expression arguments, it is generally safer to prefix wildcards or dubious path names with either ./ or to use absolute path names starting with /.

🔗 Symbolic Link Handling

• -P — Never follow symbolic links. This is the default behaviour. When find examines or prints information about files, and the file is a symbolic link, the information used shall be taken from the properties of the symbolic link itself.
• -L — Follow symbolic links. When find examines or prints information about files, the information used shall be taken from the properties of the file to which the link points, not from the link itself (unless it is a broken symbolic link or find is unable to examine the file to which the link points). Use of this option implies -noleaf. If -L is in effect and find discovers a symbolic link to a subdirectory during its search, the subdirectory pointed to by the symbolic link will be searched.
• -H — Do not follow symbolic links, except while processing the command line arguments. When find examines or prints information about files, the information used shall be taken from the properties of the symbolic link itself. The only exception is when a file specified on the command line is a symbolic link, and the link can be resolved. For that situation, the information used is taken from whatever the link points to.

If more than one of -H, -L and -P is specified, each overrides the others; the last one appearing on the command line takes effect. Since it is the default, the -P option should be considered to be in effect unless either -H or -L is specified.

🐛 Debug Options

-D debugopts — Print diagnostic information. The list of debug options should be comma separated. Valid debug options include:

• exec — Show diagnostic information relating to -exec, -execdir, -ok and -okdir
• opt — Prints diagnostic information relating to the optimisation of the expression tree
• rates — Prints a summary indicating how often each predicate succeeded or failed
• search — Navigate the directory tree verbosely
• stat — Print messages as files are examined with the stat and lstat system calls
• tree — Show the expression tree in its original and optimised form
• all — Enable all of the other debug options (but help)
• help — Explain the debugging options

⚡ Optimisation Level

-Olevel — Enables query optimisation. The find program reorders tests to speed up execution while preserving the overall effect. The optimisations performed at each optimisation level are as follows:

• 0 — Equivalent to optimisation level 1.
• 1 — Default. Expressions are reordered so that tests based only on the names of files (e.g., -name and -regex) are performed first.
• 2 — Any -type or -xtype tests are performed after name-based tests but before inode-based tests.
• 3 — Full cost-based query optimiser enabled. Cheap tests are performed first, and within each cost band, predicates are evaluated earlier or later according to whether they are likely to succeed or not.

📐 EXPRESSION

The part of the command line after the list of starting points is the expression. This is a kind of query specification describing how we match files and what we do with the files that were matched. An expression is composed of a sequence of things:

• Tests — Return a true or false value, usually on the basis of some property of a file we are considering.
• Actions — Have side effects (such as printing something on the standard output) and return either true or false, usually based on whether or not they are successful.
• Global options — Affect the operation of tests and actions specified on any part of the command line. Global options always return true.
• Positional options — Affect only tests or actions which follow them. Positional options always return true.
• Operators — Join together the other items within the expression. They include for example -o (logical OR) and -a (logical AND). Where an operator is missing, -a is assumed.

The -print action is performed on all files for which the whole expression is true, unless it contains an action other than -prune or -quit. Actions which inhibit the default -print are: -delete, -exec, -execdir, -ok, -okdir, -fls, -fprint, -fprintf, -ls, -print and -printf.

📍 Positional Options

• -daystart — Measure times (for -amin, -atime, -cmin, -ctime, -mmin, and -mtime) from the beginning of today rather than from 24 hours ago.
• -follow — Deprecated; use -L instead. Dereference symbolic links. Implies -noleaf. Affects only tests that appear after it on the command line.
• -regextype type — Changes the regular expression syntax understood by -regex and -iregex tests which occur later on the command line.
• -warn, -nowarn — Turn warning messages on or off. Default is -warn if standard input is a tty, -nowarn otherwise.

🌐 Global Options

• -d — Synonym for -depth, for compatibility with BSD systems.
• -depth — Process each directory's contents before the directory itself. -delete implies -depth.
• -help, --help — Print a summary of the command-line usage and exit.
• -ignore_readdir_race — Suppress error messages when a file is deleted between reading the directory and attempting to stat it.
• -maxdepth levels — Descend at most levels (non-negative integer) levels of directories below the starting-points.
• -mindepth levels — Do not apply any tests or actions at levels less than levels.
• -mount — Don't descend directories on other filesystems. Synonym for -xdev.
• -noignore_readdir_race — Turns off the effect of -ignore_readdir_race.
• -noleaf — Do not optimize by assuming that directories contain 2 fewer subdirectories than their hard link count.
• -version, --version — Print the find version number and exit.
• -xdev — Don't descend directories on other filesystems.

🧪 Tests

Some tests allow comparison between the file currently being examined and some reference file specified on the command line. A numeric argument n can be specified to tests as +n (greater than), -n (less than), or n (exactly).

• -amin n — File was last accessed less than, more than or exactly n minutes ago.
• -anewer reference — Time of last access of current file is more recent than last data modification of reference.
• -atime n — File was last accessed n*24 hours ago.
• -cmin n — File's status was last changed less than, more than or exactly n minutes ago.
• -cnewer reference — Time of last status change of current file is more recent than last data modification of reference.
• -ctime n — File's status was last changed n*24 hours ago.
• -empty — File is empty and is either a regular file or a directory.
• -executable — Matches files which are executable and directories which are searchable by the current user.
• -false — Always false.
• -fstype type — File is on a filesystem of type type.
• -gid n — File's numeric group ID is less than, more than or exactly n.
• -group gname — File belongs to group gname.
• -ilname pattern — Like -lname, but case insensitive.
• -iname pattern — Like -name, but case insensitive.
• -inum n — File has inode number smaller than, greater than or exactly n.
• -ipath pattern — Like -path, but case insensitive.
• -iregex pattern — Like -regex, but case insensitive.
• -iwholename pattern — See -ipath.
• -links n — File has less than, more than or exactly n hard links.
• -lname pattern — File is a symbolic link whose contents match shell pattern.
• -mmin n — File's data was last modified less than, more than or exactly n minutes ago.
• -mtime n — File's data was last modified n*24 hours ago.
• -name pattern — Base of file name matches shell pattern. The metacharacters match a leading ..
• -newer reference — Time of last data modification of current file is more recent than that of reference.
• -newerXY reference — Succeeds if timestamp X of file being considered is newer than timestamp Y of reference. X and Y can be a (access), B (birth), c (status change), m (modification), t (direct time).
• -nogroup — No group corresponds to file's numeric group ID.
• -nouser — No user corresponds to file's numeric user ID.
• -path pattern — File name matches shell pattern. The metacharacters do not treat / or . specially.
• -perm mode — File's permission bits are exactly mode (octal or symbolic).
• -perm -mode — All of the permission bits mode are set for the file.
• -perm /mode — Any of the permission bits mode are set for the file.
• -readable — Matches files which are readable by the current user.
• -regex pattern — File name matches regular expression. Default is Emacs style.
• -samefile name — File refers to the same inode as name.
• -size n[cwbkMG] — File uses less than, more than or exactly n units of space, rounding up. Suffixes: b (512-byte blocks), c (bytes), w (2-byte words), k (KiB), M (MiB), G (GiB).
• -true — Always true.
• -type c — File is of type c: b (block), c (character), d (directory), p (named pipe), f (regular file), l (symbolic link), s (socket), D (door). Multiple types can be comma-separated.
• -uid n — File's numeric user ID is less than, more than or exactly n.
• -used n — File was last accessed n days after its status was last changed.
• -user uname — File is owned by user uname.
• -wholename pattern — See -path.
• -writable — Matches files which are writable by the current user.
• -xtype c — Same as -type unless the file is a symbolic link. For symbolic links, checks the type of the file that -type does not check.
• -context pattern — (SELinux only) Security context of the file matches glob.

⚡ Actions

• -delete — Delete files; true if removal succeeded. Implies -depth.
• -exec command ; — Execute command; true if 0 status is returned. The string {} is replaced by the current file name. The command is run once per matched file.
• -exec command {} + — Variant that builds command line by appending each selected file name at the end. Only one {} allowed, must appear at the end before +.
• -execdir command ; — Like -exec but run from the subdirectory containing the matched file.
• -execdir command {} + — Like -exec + but from subdirectory.
• -fls file — Like -ls but write to file.
• -fprint file — Print full file name into file.
• -fprint0 file — Like -print0 but write to file.
• -fprintf file format — Like -printf but write to file.
• -ls — List current file in ls -dils format on standard output.
• -ok command ; — Like -exec but ask the user first.
• -okdir command ; — Like -execdir but ask the user first.
• -print — Print the full file name on standard output, followed by a newline.
• -print0 — Print the full file name followed by a null character.
• -printf format — Print format on standard output, interpreting \ escapes and % directives. (See man page for full list of directives.)
• -prune — If the file is a directory, do not descend into it. Has no effect if -depth is given.
• -quit — Exit immediately with return value zero if no errors.

🔗 Operators

Listed in order of decreasing precedence:

• ( expr ) — Force precedence (parentheses must be quoted).
• ! expr or -not expr — True if expr is false.
• expr1 expr2 — Implied -a (AND).
• expr1 -a expr2 — AND.
• expr1 -o expr2 — OR.
• expr1 , expr2 — List; both evaluated, value of expr2 is returned.

🚪 Exit Codes

find exits with status 0 if all files are processed successfully, greater than 0 if errors occur. If the return value is non-zero, you should not rely on the correctness of the results. When some error occurs, find may stop immediately without completing all specified actions.

🖥️ Examples

🔍 Simple `find|xargs` approach

$ find /tmp -name core -type f -print | xargs /bin/rm -f

Find files named core in or below /tmp and delete them. Note: This will work incorrectly if filenames contain newlines, quotes, or spaces.

🔒 Safer `find -print0 | xargs -0` approach

$ find /tmp -name core -type f -print0 | xargs -0 /bin/rm -f

Safer version that handles filenames containing special characters.

⚡ Executing a command for each file

$ find . -type f -exec file '{}' \;

Run file on every regular file in or below the current directory.

📂 Traversing the filesystem just once for 2 different actions

$ find / \
    \( -perm -4000 -fprintf /root/suid.txt '%#m %u %p\n' \) , \
    \( -size +100M -fprintf /root/big.txt '%-10s %p\n' \)

List set-user-ID files into /root/suid.txt and large files into /root/big.txt in one traversal.

⏰ Searching files by age

$ find $HOME -mtime 0

Search for files in your home directory modified in the last twenty-four hours.

🔒 Searching files by permissions

$ find /sbin /usr/sbin -executable \! -readable -print
$ find . -perm 664
$ find . -perm -664
$ find . -perm /222
$ find . -perm /220
$ find . -perm -220
$ find . -perm -444 -perm /222 \! -perm /111

Various permission searches: executable but not readable, exact permissions, all bits set, any bit set, etc.

🛑 Pruning — omitting files and subdirectories

$ cd /source-dir
$ find . -name .snapshot -prune -o \( \! -name '*~' -print0 \) \
    | cpio -pmd0 /dest-dir

Copy /source-dir to /dest-dir omitting .snapshot directories and files ending in ~.

$ find repo/ \
    \( -exec test -d '{}/.svn' \; \
    -or -exec test -d '{}/.git' \; \
    -or -exec test -d '{}/CVS' \; \
    \) -print -prune

Efficiently find SCM roots (with -prune to avoid unnecessary descent).

📚 Other useful examples

$ find /tmp -type f,d,l
$ find / \( -type f -o -type d -o -type l \)
$ find / -name needle -print -quit
$ find . .. / /tmp /tmp/TRACE compile compile/64/tests/find -maxdepth 0 -printf '[%h][%f]\n'

Search for multiple file types, stop after finding first match, demonstrate %h and %f format directives.

📚 SEE ALSO

chmod(1), locate(1), ls(1), updatedb(1), xargs(1), lstat(2), stat(2), ctime(3), fnmatch(3), printf(3), strftime(3), locatedb(5), regex(7)

Full documentation: https://www.gnu.org/software/findutils/find or available locally via: info find

📖 NAME 🚀 Quick Reference 📋 SYNOPSIS 📝 DESCRIPTION ⚙️ OPTIONS 📐 EXPRESSION 🚪 Exit Codes 🖥️ Examples 📚 SEE ALSO