mirror of
https://github.com/sharkdp/fd.git
synced 2024-11-18 18:00:35 +01:00
d63c63be8c
Add new `--min-depth <depth>` and `--exact-depth <depth>` options in addition to the existing option to limit the maximum depth. closes #404
286 lines
7.1 KiB
Groff
Vendored
286 lines
7.1 KiB
Groff
Vendored
.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).
|
|
.SH OPTIONS
|
|
.TP
|
|
.B \-H, \-\-hidden
|
|
Include hidden files and directories in the search results
|
|
(default: hidden files and directories are skipped).
|
|
.TP
|
|
.B \-I, \-\-no\-ignore
|
|
Show search results from files and directories that would otherwise be ignored by
|
|
.IR .gitignore ,
|
|
.I .ignore
|
|
or
|
|
.I .fdignore
|
|
files.
|
|
.TP
|
|
.B \-u, \-\-unrestricted
|
|
Alias for '--no-ignore'. Can be repeated; '-uu' is an alias for '--no-ignore --hidden'.
|
|
.TP
|
|
.B \-\-no\-ignore\-vcs
|
|
Show search results from files and directories that would otherwise be ignored by
|
|
.I .gitignore
|
|
files.
|
|
.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.
|
|
.TP
|
|
.B \-\-regex
|
|
Perform a regular-expression based seach (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.
|
|
.TP
|
|
.B \-a, \-\-absolute\-path
|
|
Shows the full path starting from the root as opposed to relative paths.
|
|
.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.
|
|
.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 \-\-show-errors
|
|
Enable the display of filesystem errors for situations such as insufficient
|
|
permissions or dead symlinks.
|
|
.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
|
|
.BI "\-t, \-\-type " filetype
|
|
Filter search by type:
|
|
.RS
|
|
.IP "f, file"
|
|
regular files
|
|
.IP "d, directory"
|
|
directories
|
|
.IP "l, symlink"
|
|
symbolic links
|
|
.IP "x, executable"
|
|
executable (files)
|
|
.IP "e, empty"
|
|
empty files or directories
|
|
.RE
|
|
|
|
.RS
|
|
This option can be used repeatedly to allow for multiple file types.
|
|
.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.
|
|
.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.
|
|
.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
|
|
.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
|
|
.BI "\-\-changed-within " date|duration
|
|
Filter results based on the file modification time. The argument can be provided as a specific
|
|
point in time (\fIYYYY-MM-DD HH:MM:SS\fR) or as a duration (\fI10h, 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 (\fIYYYY-MM-DD HH:MM:SS\fR) or as a duration (\fI10h, 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
|
|
.BI "\-x, \-\-exec " command
|
|
Execute
|
|
.I command
|
|
for each search result. The following placeholders are substituted by a path derived from the current search result:
|
|
.RS
|
|
.IP {}
|
|
path
|
|
.IP {/}
|
|
basename
|
|
.IP {//}
|
|
parent directory
|
|
.IP {.}
|
|
path without file extension
|
|
.IP {/.}
|
|
basename without file extension
|
|
.RE
|
|
.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
|
|
.SH PATTERN SYNTAX
|
|
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
|
|
.SH ENVIRONMENT
|
|
.TP
|
|
.B LS_COLORS
|
|
Determines how to colorize search results, see
|
|
.BR dircolors (1) .
|
|
.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 extention " .py ") in the current directory:"
|
|
$ fd -e py
|
|
.TP
|
|
.RI "Open all search results with vim:"
|
|
$ fd pattern -X vim
|
|
.SH SEE ALSO
|
|
.BR find (1)
|