2017-10-25 19:16:35 +00:00
.TH FD 1
2017-10-17 13:50:55 +00:00
.SH NAME
2017-10-25 19:16:35 +00:00
fd \- find entries in the filesystem
2017-10-17 13:50:55 +00:00
.SH SYNOPSIS
2017-10-19 13:57:27 +00:00
.B fd
2017-10-25 20:43:36 +00:00
.RB [ \- HIEsiaLp0hV ]
2017-10-25 19:16:35 +00:00
.RB [ \- d
2017-10-17 13:50:55 +00:00
.IR depth ]
.RB [ \- t
.IR filetype ]
.RB [ \- e
.IR ext ]
2017-10-25 20:43:36 +00:00
.RB [ \- E
.IR exclude ]
2017-10-17 13:50:55 +00:00
.RB [ \- c
.IR when ]
.RB [ \- j
.IR num ]
2017-10-19 13:57:27 +00:00
.RB [ \- x
2017-11-15 22:34:32 +00:00
.IR cmd ]
2017-10-17 13:50:55 +00:00
.RI [ pattern ]
2017-12-10 05:40:13 +00:00
.RI [ path... ]
2017-10-17 13:50:55 +00:00
.SH DESCRIPTION
.B fd
is a simple, fast and user-friendly alternative to
.BR find (1).
.SH OPTIONS
.TP
.B \- H, \- \- hidden
2018-10-27 15:07:09 +00:00
Include hidden files and directories in the search results
(default: hidden files and directories are skipped).
2017-10-17 13:50:55 +00:00
.TP
2017-10-19 13:57:27 +00:00
.B \- I, \- \- no\-ignore
2018-10-27 15:07:09 +00:00
Show search results from files and directories that would otherwise be ignored by
.IR .gitignore ,
.I .ignore
or
2018-02-21 20:41:52 +00:00
.I .fdignore
2018-10-27 15:07:09 +00:00
files.
2017-11-21 21:54:00 +00:00
.TP
2019-09-17 19:57:10 +00:00
.B \- u, \- \- unrestricted
Alias for '--no-ignore'. Can be repeated; '-uu' is an alias for '--no-ignore --hidden'.
.TP
2017-11-21 21:54:00 +00:00
.B \- \- no\-ignore\-vcs
2018-10-27 15:07:09 +00:00
Show search results from files and directories that would otherwise be ignored by
.I .gitignore
files.
2017-10-17 13:50:55 +00:00
.TP
2017-10-19 13:57:27 +00:00
.B \- s, \- \- case\-sensitive
2018-10-27 15:07:09 +00:00
Perform a case-sensitive search. By default, fd uses case-insensitive searches, unless the
pattern contains an uppercase character (smart case).
2017-10-17 13:50:55 +00:00
.TP
2017-10-25 19:16:35 +00:00
.B \- i, \- \- ignore\-case
2018-10-27 15:07:09 +00:00
Perform a case-insensitive search. By default, fd uses case-insensitive searches, unless the
pattern contains an uppercase character (smart case).
2017-10-25 19:16:35 +00:00
.TP
2019-09-15 15:10:31 +00:00
.B \- g, \- \- glob
Perform a glob-based search instead of a regular expression search.
.TP
.B \- \- regex
Perform a regular-expression based seach (default). This can be used to override --glob.
.TP
2018-02-10 14:19:53 +00:00
.B \- F, \- \- fixed\-strings
Treat the pattern as a literal string instead of a regular expression.
.TP
2017-10-17 13:50:55 +00:00
.B \- a, \- \- absolute\-path
2018-10-27 15:07:09 +00:00
Shows the full path starting from the root as opposed to relative paths.
2017-10-17 13:50:55 +00:00
.TP
2020-04-03 07:39:33 +00:00
.B \- l, \- \- list\-details
2020-04-02 19:40:57 +00:00
Use a detailed listing format like 'ls -l'. This is basically an alias
for '--exec-batch ls -l' with some additional 'ls' options. This can be used
2020-04-03 08:07:46 +00:00
to see more metadata, to show symlink targets and to achieve a deterministic
sort order.
2020-04-02 19:40:57 +00:00
.TP
2017-10-17 13:50:55 +00:00
.B \- L, \- \- follow
2018-10-27 15:07:09 +00:00
By default, fd does not descend into symlinked directories. Using this flag, symbolic links are
also traversed.
2017-10-17 13:50:55 +00:00
.TP
.B \- p, \- \- full\-path
2018-10-27 15:07:09 +00:00
By default, the search pattern is only matched against the filename (or directory name). Using
this flag, the
2017-10-17 13:50:55 +00:00
.I pattern
2018-10-27 15:07:09 +00:00
is matched against the full path.
2017-10-17 13:50:55 +00:00
.TP
.B \- 0 , \- \- print0
2018-10-27 15:07:09 +00:00
Separate search results by the null character (instead of newlines). Useful for piping results to
.IR xargs .
.TP
2020-04-02 15:52:44 +00:00
.B \- \- max\-results count
Limit the number of search results to 'count' and quit immediately.
.TP
2018-10-27 15:07:09 +00:00
.B \- \- show-errors
Enable the display of filesystem errors for situations such as insufficient
permissions or dead symlinks.
2017-10-17 13:50:55 +00:00
.TP
2020-03-15 21:03:51 +00:00
.B \- \- one\-file\-system, \- \- mount, \- \- xdev
By default, fd will traverse the file system tree as far as other options dictate. With this flag, fd ensures that it does not descend into a different file system than the one it started in. Comparable to the -mount or -xdev filters of find(1).
.TP
2017-10-17 13:50:55 +00:00
.B \- h, \- \- help
2018-01-03 09:28:34 +00:00
Print help information.
2017-10-17 13:50:55 +00:00
.TP
2017-10-19 13:57:27 +00:00
.B \- V, \- \- version
2018-01-03 09:28:34 +00:00
Print version information.
2017-10-17 13:50:55 +00:00
.TP
2018-01-03 09:28:34 +00:00
.BI "\-d, \-\-max\-depth " d
2017-10-17 13:50:55 +00:00
Limit directory traversal to at most
2018-01-03 09:28:34 +00:00
.I d
levels of depth. By default, there is no limit on the search depth.
2017-10-17 13:50:55 +00:00
.TP
2017-10-25 19:16:35 +00:00
.BI "\-t, \-\-type " filetype
2017-10-17 13:50:55 +00:00
Filter search by type:
.RS
.IP "f, file"
regular files
2019-02-18 23:26:57 +00:00
.IP "d, directory"
2017-10-17 13:50:55 +00:00
directories
2018-02-21 21:58:22 +00:00
.IP "l, symlink"
2017-10-17 13:50:55 +00:00
symbolic links
2018-03-26 08:25:33 +00:00
.IP "x, executable"
executable (files)
2018-08-19 15:05:04 +00:00
.IP "e, empty"
empty files or directories
2017-10-17 13:50:55 +00:00
.RE
2018-01-03 09:28:34 +00:00
.RS
This option can be used repeatedly to allow for multiple file types.
.RE
2017-10-17 13:50:55 +00:00
.TP
.BI "\-e, \-\-extension " ext
Filter search results by file extension
.IR ext .
2018-01-03 09:28:34 +00:00
This option can be used repeatedly to allow for multiple possible file extensions.
2017-10-25 20:43:36 +00:00
.TP
.BI "\-E, \-\-exclude " pattern
Exclude files/directories that match the given glob pattern.
This overrides any other ignore logic.
Multiple exclude patterns can be specified.
2017-10-17 13:50:55 +00:00
.TP
2018-03-26 08:25:33 +00:00
.BI "\-\-ignore-file " path
Add a custom ignore-file in '.gitignore' format.
These files have a low precedence.
.TP
2017-10-17 13:50:55 +00:00
.BI "\-c, \-\-color " when
Declare
.I when
2017-10-19 13:57:27 +00:00
to colorize search results:
2017-10-17 13:50:55 +00:00
.RS
.IP auto
2017-10-25 19:16:35 +00:00
Colorize output when standard output is connected to terminal (default).
2017-10-17 13:50:55 +00:00
.IP never
2017-10-19 13:57:27 +00:00
Do not colorize output.
2017-10-17 13:50:55 +00:00
.IP always
2017-10-19 13:57:27 +00:00
Always colorize output.
2017-10-17 13:50:55 +00:00
.RE
.TP
.BI "\-j, \-\-threads " num
2019-06-11 04:34:36 +00:00
Set number of threads to use for searching & executing (default: number of available CPU cores).
2017-10-19 13:57:27 +00:00
.TP
2018-08-19 16:50:47 +00:00
.BI "\-S, \-\-size " size
Limit results based on the size of files using the format
.I <+-><NUM><UNIT>
.RS
.IP '+'
file size must be greater than or equal to this
.IP '-'
file size must be less than or equal to this
.IP 'NUM'
The numeric size (e.g. 500)
.IP 'UNIT'
The units for NUM. They are not case-sensitive.
Allowed unit values:
.RS
.IP 'b'
bytes
.IP 'k'
kilobytes
.IP 'm'
megabytes
.IP 'g'
gigabytes
.IP 't'
terabytes
.IP 'ki'
kibibytes
.IP 'mi'
mebibytes
.IP 'gi'
gibibytes
.IP 'ti'
tebibytes
.RE
.RE
.TP
2018-10-27 15:07:09 +00:00
.BI "\-\-changed-within " date|duration
Filter results based on the file modification time. The argument can be provided as a specific
point in time (\fI YYYY-MM-DD HH:MM:SS\fR ) or as a duration (\fI 10h, 1d, 35min\fR ).
.B --change-newer-than
can be used as an alias.
Examples:
\- \- changed-within 2weeks
\- \- change-newer-than "2018-10-27 10:00:00"
.TP
.BI "\-\-changed-before " date|duration
Filter results based on the file modification time. The argument can be provided as a specific
point in time (\fI YYYY-MM-DD HH:MM:SS\fR ) or as a duration (\fI 10h, 1d, 35min\fR ).
.B --change-older-than
can be used as an alias.
Examples:
\- \- changed-before "2018-10-27 10:00:00"
\- \- change-older-than 2weeks
.TP
2019-02-13 19:04:37 +00:00
.BI "\-x, \-\-exec " command
2017-10-19 13:57:27 +00:00
Execute
.I command
2017-11-15 02:19:28 +00:00
for each search result. The following placeholders are substituted by a path derived from the current search result:
2017-10-19 13:57:27 +00:00
.RS
.IP {}
path
.IP {/}
2017-11-15 02:19:28 +00:00
basename
2017-10-19 13:57:27 +00:00
.IP {//}
2017-11-15 02:19:28 +00:00
parent directory
.IP {.}
path without file extension
2017-10-19 13:57:27 +00:00
.IP {/.}
2017-11-15 02:19:28 +00:00
basename without file extension
2017-10-19 13:57:27 +00:00
.RE
2019-02-13 19:04:37 +00:00
.TP
.BI "\-X, \-\-exec-batch " command
Execute
.I command
with all search results at once.
A single occurence of the following placeholders is authorized and substituted by the paths derived from the search results before the command is executed:
.RS
.IP {}
path
.IP {/}
basename
.IP {//}
parent directory
.IP {.}
path without file extension
.IP {/.}
basename without file extension
.RE
2019-11-16 16:11:41 +00:00
.SH PATTERN SYNTAX
2019-11-24 23:13:50 +00:00
The regular expression syntax used by fd is documented here:
.UR https://docs.rs/regex/1.0.0/regex/#syntax
.UE
The glob syntax is documented here:
.UR https://docs.rs/globset/#syntax
.UE
2017-10-17 13:50:55 +00:00
.SH ENVIRONMENT
.TP
2017-10-19 13:57:27 +00:00
.B LS_COLORS
Determines how to colorize search results, see
.BR dircolors (1) .
2017-10-17 13:50:55 +00:00
.SH EXAMPLES
.TP
2017-10-25 19:16:35 +00:00
.RI "Find files and directories that match the pattern '" needle "':"
$ fd needle
.TP
.RI "Start a search in a given directory (" /var/log "):"
2017-10-19 13:57:27 +00:00
$ fd nginx /var/log
2017-10-17 13:50:55 +00:00
.TP
2017-10-25 19:16:35 +00:00
.RI "Find all Python files (all files with the extention " .py ") in the current directory:"
2017-10-17 13:50:55 +00:00
$ fd -e py
2019-02-13 19:04:37 +00:00
.TP
.RI "Open all search results with vim:"
$ fd pattern -X vim
2017-10-17 13:50:55 +00:00
.SH SEE ALSO
.BR find (1)