mirror of https://github.com/sharkdp/fd.git
532 lines
16 KiB
Groff
532 lines
16 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.
|
||
.P
|
||
By default
|
||
.B fd
|
||
will exclude hidden files and directories, as well as any files that match gitignore rules
|
||
or ignore rules in .ignore or .fdignore files.
|
||
.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'.
|
||
.IP
|
||
Ignored files are still excluded unless \-\-no\-ignore or \-\-no\-ignore\-vcs
|
||
is also used.
|
||
.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\-require\-git
|
||
Do not require a git repository to respect gitignores. By default, fd will only
|
||
respect global gitignore rules, .gitignore rules and local exclude rules if fd
|
||
detects that you are searching inside a git repository. This flag allows you to
|
||
relax this restriction such that fd will respect all git related ignore rules
|
||
regardless of whether you’re searching in a git repository or not. The flag can
|
||
be overridden with '--require-git'.
|
||
.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
|
||
.BI "\-\-and " pattern
|
||
Add additional required search patterns, all of which must be matched. Multiple additional
|
||
patterns can be specified. The patterns are regular expressions, unless '\-\-glob'
|
||
or '\-\-fixed\-strings' is used.
|
||
.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, dir, directory"
|
||
directories
|
||
.IP "l, symlink"
|
||
symbolic links
|
||
.IP "b, block-device"
|
||
block devices
|
||
.IP "c, char-device"
|
||
character devices
|
||
.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 as full RFC3339 format with time zone, as a date or datetime in the
|
||
local time zone (\fIYYYY-MM-DD\fR or \fIYYYY-MM-DD HH:MM:SS\fR), or as the prefix '@'
|
||
followed by the number of seconds since the Unix epoch (@[0-9]+).
|
||
\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
|
||
\-\-changed-after @1704067200
|
||
.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 as full RFC3339 format with time zone, as a date or datetime in the
|
||
local time zone (\fIYYYY-MM-DD\fR or \fIYYYY-MM-DD HH:MM:SS\fR), or as the prefix '@'
|
||
followed by the number of seconds since the Unix epoch (@[0-9]+).
|
||
.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
|
||
\-\-older @1704067200
|
||
.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.
|
||
|
||
If parallelism is enabled, the order commands will be executed in is non-deterministic. And even with
|
||
--threads=1, the order is determined by the operating system and may not be what you expect. Thus, it is
|
||
recommended that you don't rely on any ordering of the results.
|
||
|
||
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
|
||
.IP {{
|
||
literal '{' (an escape sequence)
|
||
.IP }}
|
||
literal '}' (an escape sequence)
|
||
.RE
|
||
|
||
If no placeholder is present, an implicit "{}" at the end is assumed.
|
||
|
||
Notice that you can use "{{" and "}}" to escape "{" and "}" respectively, which is especially
|
||
useful if you need to include the literal text of one of the above placeholders.
|
||
|
||
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.
|
||
|
||
The order of the arguments is non-deterministic and should not be relied upon.
|
||
|
||
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 FILES
|
||
.TP
|
||
.B .fdignore
|
||
This file works similarly to a .gitignore file anywhere in the searched tree and specifies patterns
|
||
that should be excluded from the search. However, this file is specific to fd, and will be used even
|
||
if the --no-ignore-vcs option is used.
|
||
.TP
|
||
.B $XDG_CONFIG_HOME/fd/ignore
|
||
Global ignore file. Unless ignore mode is turned off (such as with --no-ignore)
|
||
ignore entries in this file will be ignored, as if it was an .fdignore file in the
|
||
current directory.
|
||
.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 Tips and Tricks
|
||
.IP \[bu]
|
||
If you add ".git/" to your global ignore file ($XDG_CONFIG_HOME/fd/ignore), then
|
||
".git" folders will be ignored by default, even when the --hidden option is used.
|
||
.IP \[bu]
|
||
You can use a shell alias or a wrapper script in order to pass desired flags to fd
|
||
by default. For example if you do not like the default behavior of respecting gitignore,
|
||
you can use
|
||
`alias fd="/usr/bin/fd --no-ignore-vcs"`
|
||
in your .bashrc to create an alias for fd that doesn't ignore git files by default.
|
||
.SH BUGS
|
||
Bugs can be reported on GitHub: https://github.com/sharkdp/fd/issues
|
||
.SH SEE ALSO
|
||
.BR find (1)
|