mirror of https://github.com/sharkdp/fd.git
468 lines
13 KiB
Groff
468 lines
13 KiB
Groff
.TH FD 1
|
|
.SH NAME
|
|
fd \- find entries in the filesystem
|
|
.SH SYNOPSIS
|
|
.B fd
|
|
.RB [ \-HIEsiaLp0hV ]
|
|
.RB [ \-d
|
|
.IR depth ]
|
|
.RB [ \-t
|
|
.IR filetype ]
|
|
.RB [ \-e
|
|
.IR ext ]
|
|
.RB [ \-E
|
|
.IR exclude ]
|
|
.RB [ \-c
|
|
.IR when ]
|
|
.RB [ \-j
|
|
.IR num ]
|
|
.RB [ \-x
|
|
.IR cmd ]
|
|
.RI [ pattern ]
|
|
.RI [ path... ]
|
|
.SH DESCRIPTION
|
|
.B fd
|
|
is a simple, fast and user-friendly alternative to
|
|
.BR find (1).
|
|
.P
|
|
By default
|
|
.B fd
|
|
uses regular expressions for the pattern. However, this can be changed to use simple glob patterns
|
|
with the '\-\-glob' option.
|
|
.SH OPTIONS
|
|
.TP
|
|
.B \-H, \-\-hidden
|
|
Include hidden files and directories in the search results
|
|
(default: hidden files and directories are skipped). The flag can be overridden with '--no-hidden'.
|
|
.TP
|
|
.B \-I, \-\-no\-ignore
|
|
Show search results from files and directories that would otherwise be ignored by
|
|
.RS
|
|
.IP \[bu] 2
|
|
.I .gitignore
|
|
.IP \[bu]
|
|
.I .git/info/exclude
|
|
.IP \[bu]
|
|
The global gitignore configuration (by default
|
|
.IR $HOME/.config/git/ignore )
|
|
.IP \[bu]
|
|
.I .ignore
|
|
.IP \[bu]
|
|
.I .fdignore
|
|
.IP \[bu]
|
|
The global fd ignore file (usually
|
|
.I $HOME/.config/fd/ignore
|
|
)
|
|
.RE
|
|
.IP
|
|
The flag can be overridden with '--ignore'.
|
|
.TP
|
|
.B \-u, \-\-unrestricted
|
|
Perform an unrestricted search, including ignored and hidden files. This is an alias for '--hidden --no-ignore'.
|
|
.TP
|
|
.B \-\-no\-ignore\-vcs
|
|
Show search results from files and directories that would otherwise be ignored by gitignore files
|
|
including
|
|
.IR .gitignore ,
|
|
.IR .git/info/exclude ,
|
|
and the global gitignore configuration
|
|
.RI ( core.excludesFile
|
|
git setting, which defaults to
|
|
.IR $HOME/.config/git/ignore ).
|
|
The flag can be overridden with '--ignore-vcs'.
|
|
.TP
|
|
.B \-\-no\-ignore\-parent
|
|
Show search results from files and directories that would otherwise be ignored by gitignore files in
|
|
parent directories.
|
|
.TP
|
|
.B \-s, \-\-case\-sensitive
|
|
Perform a case-sensitive search. By default, fd uses case-insensitive searches, unless the
|
|
pattern contains an uppercase character (smart case).
|
|
.TP
|
|
.B \-i, \-\-ignore\-case
|
|
Perform a case-insensitive search. By default, fd uses case-insensitive searches, unless the
|
|
pattern contains an uppercase character (smart case).
|
|
.TP
|
|
.B \-g, \-\-glob
|
|
Perform a glob-based search instead of a regular expression search.
|
|
If combined with the '\-\-full-path' option, '**' can be used to match multiple path components.
|
|
.TP
|
|
.B \-\-regex
|
|
Perform a regular-expression based search (default). This can be used to override --glob.
|
|
.TP
|
|
.B \-F, \-\-fixed\-strings
|
|
Treat the pattern as a literal string instead of a regular expression. Note that this also
|
|
performs substring comparison. If you want to match on an exact filename, consider using '\-\-glob'.
|
|
.TP
|
|
.B \-a, \-\-absolute\-path
|
|
Shows the full path starting from the root as opposed to relative paths.
|
|
The flag can be overridden with '--relative-path'.
|
|
.TP
|
|
.B \-l, \-\-list\-details
|
|
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
|
|
to see more metadata, to show symlink targets and to achieve a deterministic
|
|
sort order.
|
|
.TP
|
|
.B \-L, \-\-follow
|
|
By default, fd does not descend into symlinked directories. Using this flag, symbolic links are
|
|
also traversed. The flag can be overridden with '--no-follow'.
|
|
.TP
|
|
.B \-p, \-\-full\-path
|
|
By default, the search pattern is only matched against the filename (or directory name). Using
|
|
this flag, the
|
|
.I pattern
|
|
is matched against the full path.
|
|
.TP
|
|
.B \-0, \-\-print0
|
|
Separate search results by the null character (instead of newlines). Useful for piping results to
|
|
.IR xargs .
|
|
.TP
|
|
.B \-\-max\-results count
|
|
Limit the number of search results to 'count' and quit immediately.
|
|
.TP
|
|
.B \-1
|
|
Limit the search to a single result and quit immediately. This is an alias for '--max-results=1'.
|
|
.TP
|
|
.B \-q, \-\-quiet
|
|
When the flag is present, the program does not print anything and will instead exit with a code of 0 if there is at least one search result.
|
|
Otherwise, the exit code will be 1.
|
|
This is mainly for usage in scripts and can be faster than checking for output because the search can be stopped early after the first match.
|
|
.B \-\-has\-results
|
|
can be used as an alias.
|
|
.TP
|
|
.B \-\-show-errors
|
|
Enable the display of filesystem errors for situations such as insufficient
|
|
permissions or dead symlinks.
|
|
.TP
|
|
.B \-\-strip-cwd-prefix
|
|
By default, relative paths are prefixed with './' when the output goes to a non interactive terminal
|
|
(TTY). Use this flag to disable this behaviour.
|
|
.TP
|
|
.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
|
|
.B \-h, \-\-help
|
|
Print help information.
|
|
.TP
|
|
.B \-V, \-\-version
|
|
Print version information.
|
|
.TP
|
|
.BI "\-d, \-\-max\-depth " d
|
|
Limit directory traversal to at most
|
|
.I d
|
|
levels of depth. By default, there is no limit on the search depth.
|
|
.TP
|
|
.BI "\-\-min\-depth " d
|
|
Only show search results starting at the given depth. See also: '--max-depth' and '--exact-depth'.
|
|
.TP
|
|
.BI "\-\-exact\-depth " d
|
|
Only show search results at the exact given depth. This is an alias for '--min-depth <depth> --max-depth <depth>'.
|
|
.TP
|
|
.B \-\-prune
|
|
Do not traverse into matching directories.
|
|
.TP
|
|
.BI "\-t, \-\-type " filetype
|
|
Filter search by type:
|
|
.RS
|
|
.IP "f, file"
|
|
regular files
|
|
.IP "d, directory"
|
|
directories
|
|
.IP "l, symlink"
|
|
symbolic links
|
|
.IP "s, socket"
|
|
sockets
|
|
.IP "p, pipe"
|
|
named pipes (FIFOs)
|
|
.IP "x, executable"
|
|
executable (files)
|
|
.IP "e, empty"
|
|
empty files or directories
|
|
.RE
|
|
|
|
.RS
|
|
This option can be specified more than once to include multiple file types.
|
|
Searching for '--type file --type symlink' will show both regular files as well as
|
|
symlinks. Note that the 'executable' and 'empty' filters work differently: '--type
|
|
executable' implies '--type file' by default. And '--type empty' searches for
|
|
empty files and directories, unless either '--type file' or '--type directory' is
|
|
specified in addition.
|
|
|
|
Examples:
|
|
- Only search for files:
|
|
fd --type file …
|
|
fd -tf …
|
|
- Find both files and symlinks
|
|
fd --type file --type symlink …
|
|
fd -tf -tl …
|
|
- Find executable files:
|
|
fd --type executable
|
|
fd -tx
|
|
- Find empty files:
|
|
fd --type empty --type file
|
|
fd -te -tf
|
|
- Find empty directories:
|
|
fd --type empty --type directory
|
|
fd -te -td
|
|
.RE
|
|
.TP
|
|
.BI "\-e, \-\-extension " ext
|
|
Filter search results by file extension
|
|
.IR ext .
|
|
This option can be used repeatedly to allow for multiple possible file extensions.
|
|
|
|
If you want to search for files without extension, you can use the regex '^[^.]+$'
|
|
as a normal search pattern.
|
|
.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.
|
|
Examples:
|
|
\-\-exclude '*.pyc'
|
|
\-\-exclude node_modules
|
|
.TP
|
|
.BI "\-\-ignore-file " path
|
|
Add a custom ignore-file in '.gitignore' format.
|
|
These files have a low precedence.
|
|
.TP
|
|
.BI "\-c, \-\-color " when
|
|
Declare
|
|
.I when
|
|
to colorize search results:
|
|
.RS
|
|
.IP auto
|
|
Colorize output when standard output is connected to terminal (default).
|
|
.IP never
|
|
Do not colorize output.
|
|
.IP always
|
|
Always colorize output.
|
|
.RE
|
|
.TP
|
|
.BI "\-j, \-\-threads " num
|
|
Set number of threads to use for searching & executing (default: number of available CPU cores).
|
|
.TP
|
|
.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
|
|
.P
|
|
If neither '+' nor '-' is specified, file size must be exactly 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 (base ten, 10^3 = 1000 bytes)
|
|
.IP 'm'
|
|
megabytes
|
|
.IP 'g'
|
|
gigabytes
|
|
.IP 't'
|
|
terabytes
|
|
.IP 'ki'
|
|
kibibytes (base two, 2^10 = 1024 bytes)
|
|
.IP 'mi'
|
|
mebibytes
|
|
.IP 'gi'
|
|
gibibytes
|
|
.IP 'ti'
|
|
tebibytes
|
|
.RE
|
|
.RE
|
|
.TP
|
|
.BI "\-\-changed-within " date|duration
|
|
Filter results based on the file modification time.
|
|
Files with modification times greater than the argument will be returned.
|
|
The argument can be provided as a duration (\fI10h, 1d, 35min\fR) or as a specific point
|
|
in time in either full RFC3339 format with time zone, or as a date or datetime in the
|
|
local time zone (\fIYYYY-MM-DD\fR or \fIYYYY-MM-DD HH:MM:SS\fR).
|
|
\fB\-\-change-newer-than\fR,
|
|
.B --newer
|
|
or
|
|
.B --changed-after
|
|
can be used as aliases.
|
|
|
|
Examples:
|
|
\-\-changed-within 2weeks
|
|
\-\-change-newer-than "2018-10-27 10:00:00"
|
|
\-\-newer 2018-10-27
|
|
.TP
|
|
.BI "\-\-changed-before " date|duration
|
|
Filter results based on the file modification time.
|
|
Files with modification times less than the argument will be returned.
|
|
The argument can be provided as a duration (\fI10h, 1d, 35min\fR) or as a specific point
|
|
in time in either full RFC3339 format with time zone, or as a date or datetime in the
|
|
local time zone (\fIYYYY-MM-DD\fR or \fIYYYY-MM-DD HH:MM:SS\fR).
|
|
.B --change-older-than
|
|
or
|
|
.B --older
|
|
can be used as aliases.
|
|
|
|
Examples:
|
|
\-\-changed-before "2018-10-27 10:00:00"
|
|
\-\-change-older-than 2weeks
|
|
.TP
|
|
.BI "-o, \-\-owner " [user][:group]
|
|
Filter files by their user and/or group. Format: [(user|uid)][:(group|gid)]. Either side
|
|
is optional. Precede either side with a '!' to exclude files instead.
|
|
|
|
Examples:
|
|
\-\-owner john
|
|
\-\-owner :students
|
|
\-\-owner "!john:students"
|
|
.TP
|
|
.BI "\-\-base\-directory " path
|
|
Change the current working directory of fd to the provided path. This means that search results will
|
|
be shown with respect to the given base path. Note that relative paths which are passed to fd via the
|
|
positional \fIpath\fR argument or the \fB\-\-search\-path\fR option will also be resolved relative to
|
|
this directory.
|
|
.TP
|
|
.BI "\-\-path\-separator " separator
|
|
Set the path separator to use when printing file paths. The default is the OS-specific separator
|
|
('/' on Unix, '\\' on Windows).
|
|
.TP
|
|
.BI "\-\-search\-path " search\-path
|
|
Provide paths to search as an alternative to the positional \fIpath\fR argument. Changes the usage to
|
|
\'fd [FLAGS/OPTIONS] \-\-search\-path PATH \-\-search\-path PATH2 [PATTERN]\'
|
|
.TP
|
|
.BI "\-x, \-\-exec " command
|
|
.RS
|
|
Execute
|
|
.I command
|
|
for each search result in parallel (use --threads=1 for sequential command execution).
|
|
|
|
Note that all subsequent positional arguments are considered to be arguments to the
|
|
.I command
|
|
- not to fd.
|
|
It is therefore recommended to place the \-x/\-\-exec option last. Alternatively, you can supply
|
|
a ';' argument to end the argument list and continue with more fd options.
|
|
Most shells require ';' to be escaped: '\\;'.
|
|
This option can be specified multiple times, in which case all commands are run for each
|
|
file found, in the order they are provided. In that case, you must supply a ';' argument for
|
|
all but the last commands.
|
|
|
|
The following placeholders are substituted before the command is executed:
|
|
.RS
|
|
.IP {}
|
|
path (of the current search result)
|
|
.IP {/}
|
|
basename
|
|
.IP {//}
|
|
parent directory
|
|
.IP {.}
|
|
path without file extension
|
|
.IP {/.}
|
|
basename without file extension
|
|
.RE
|
|
|
|
If no placeholder is present, an implicit "{}" at the end is assumed.
|
|
|
|
Examples:
|
|
|
|
- find all *.zip files and unzip them:
|
|
|
|
fd -e zip -x unzip
|
|
|
|
- find *.h and *.cpp files and run "clang-format -i .." for each of them:
|
|
|
|
fd -e h -e cpp -x clang-format -i
|
|
|
|
- Convert all *.jpg files to *.png files:
|
|
|
|
fd -e jpg -x convert {} {.}.png
|
|
.RE
|
|
.TP
|
|
.BI "\-X, \-\-exec-batch " command
|
|
.RS
|
|
Execute
|
|
.I command
|
|
once, with all search results as arguments.
|
|
One of the following placeholders is substituted before the command is executed:
|
|
.RS
|
|
.IP {}
|
|
path (of all search results)
|
|
.IP {/}
|
|
basename
|
|
.IP {//}
|
|
parent directory
|
|
.IP {.}
|
|
path without file extension
|
|
.IP {/.}
|
|
basename without file extension
|
|
.RE
|
|
|
|
If no placeholder is present, an implicit "{}" at the end is assumed.
|
|
|
|
Like \-\-exec, this can be used multiple times, in which case each command will be run in
|
|
the order given.
|
|
|
|
Examples:
|
|
|
|
- Find all test_*.py files and open them in your favorite editor:
|
|
|
|
fd -g 'test_*.py' -X vim
|
|
|
|
Note that this executes a single "vim" process with all search results as arguments.
|
|
|
|
- Find all *.rs files and count the lines with "wc -l ...":
|
|
|
|
fd -e rs -X wc -l
|
|
.RE
|
|
.TP
|
|
.BI "\-\-batch-size " size
|
|
Maximum number of arguments to pass to the command given with -X. If the number of results is
|
|
greater than the given size, the command given with -X is run again with remaining arguments. A
|
|
batch size of zero means there is no limit (default), but note that batching might still happen
|
|
due to OS restrictions on the maximum length of command lines.
|
|
.SH PATTERN SYNTAX
|
|
The regular expression syntax used by fd is documented here:
|
|
|
|
https://docs.rs/regex/1.0.0/regex/#syntax
|
|
|
|
The glob syntax is documented here:
|
|
|
|
https://docs.rs/globset/#syntax
|
|
.SH ENVIRONMENT
|
|
.TP
|
|
.B LS_COLORS
|
|
Determines how to colorize search results, see
|
|
.BR dircolors (1) .
|
|
.TP
|
|
.B NO_COLOR
|
|
Disables colorized output.
|
|
.TP
|
|
.B XDG_CONFIG_HOME, HOME
|
|
Used to locate the global ignore file. If
|
|
.B XDG_CONFIG_HOME
|
|
is set, use
|
|
.IR $XDG_CONFIG_HOME/fd/ignore .
|
|
Otherwise, use
|
|
.IR $HOME/.config/fd/ignore .
|
|
.SH EXAMPLES
|
|
.TP
|
|
.RI "Find files and directories that match the pattern '" needle "':"
|
|
$ fd needle
|
|
.TP
|
|
.RI "Start a search in a given directory (" /var/log "):"
|
|
$ fd nginx /var/log
|
|
.TP
|
|
.RI "Find all Python files (all files with the extension " .py ") in the current directory:"
|
|
$ fd -e py
|
|
.TP
|
|
.RI "Open all search results with vim:"
|
|
$ fd pattern -X vim
|
|
.SH BUGS
|
|
Bugs can be reported on GitHub: https://github.com/sharkdp/fd/issues
|
|
.SH SEE ALSO
|
|
.BR find (1)
|