fd/doc/fd.1

334 lines
8.9 KiB
Groff
Raw Normal View History

2017-10-25 21:16:35 +02:00
.TH FD 1
2017-10-17 15:50:55 +02:00
.SH NAME
2017-10-25 21:16:35 +02:00
fd \- find entries in the filesystem
2017-10-17 15:50:55 +02:00
.SH SYNOPSIS
.B fd
2017-10-25 22:43:36 +02:00
.RB [ \-HIEsiaLp0hV ]
2017-10-25 21:16:35 +02:00
.RB [ \-d
2017-10-17 15:50:55 +02:00
.IR depth ]
.RB [ \-t
.IR filetype ]
.RB [ \-e
.IR ext ]
2017-10-25 22:43:36 +02:00
.RB [ \-E
.IR exclude ]
2017-10-17 15:50:55 +02:00
.RB [ \-c
.IR when ]
.RB [ \-j
.IR num ]
.RB [ \-x
2017-11-15 23:34:32 +01:00
.IR cmd ]
2017-10-17 15:50:55 +02:00
.RI [ pattern ]
2017-12-10 06:40:13 +01:00
.RI [ path... ]
2017-10-17 15:50:55 +02: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 17:07:09 +02:00
Include hidden files and directories in the search results
(default: hidden files and directories are skipped).
2017-10-17 15:50:55 +02:00
.TP
.B \-I, \-\-no\-ignore
2018-10-27 17:07:09 +02:00
Show search results from files and directories that would otherwise be ignored by
.IR .gitignore ,
2020-04-25 21:32:17 +02:00
.IR .ignore ,
.IR .fdignore ,
or the global ignore file.
.TP
2019-09-17 21:57:10 +02:00
.B \-u, \-\-unrestricted
Alias for '--no-ignore'. Can be repeated; '-uu' is an alias for '--no-ignore --hidden'.
.TP
.B \-\-no\-ignore\-vcs
2018-10-27 17:07:09 +02:00
Show search results from files and directories that would otherwise be ignored by
.I .gitignore
files.
2017-10-17 15:50:55 +02:00
.TP
.B \-s, \-\-case\-sensitive
2018-10-27 17:07:09 +02: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 15:50:55 +02:00
.TP
2017-10-25 21:16:35 +02:00
.B \-i, \-\-ignore\-case
2018-10-27 17:07:09 +02: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 21:16:35 +02:00
.TP
2019-09-15 17:10:31 +02:00
.B \-g, \-\-glob
Perform a glob-based search instead of a regular expression search.
.TP
.B \-\-regex
2020-12-04 07:52:58 +01:00
Perform a regular-expression based search (default). This can be used to override --glob.
2019-09-15 17:10:31 +02:00
.TP
2018-02-10 15:19:53 +01:00
.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'.
2018-02-10 15:19:53 +01:00
.TP
2017-10-17 15:50:55 +02:00
.B \-a, \-\-absolute\-path
2018-10-27 17:07:09 +02:00
Shows the full path starting from the root as opposed to relative paths.
2017-10-17 15:50:55 +02:00
.TP
2020-04-03 09:39:33 +02:00
.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
2017-10-17 15:50:55 +02:00
.B \-L, \-\-follow
2018-10-27 17:07:09 +02:00
By default, fd does not descend into symlinked directories. Using this flag, symbolic links are
also traversed.
2017-10-17 15:50:55 +02:00
.TP
.B \-p, \-\-full\-path
2018-10-27 17:07:09 +02:00
By default, the search pattern is only matched against the filename (or directory name). Using
this flag, the
2017-10-17 15:50:55 +02:00
.I pattern
2018-10-27 17:07:09 +02:00
is matched against the full path.
2017-10-17 15:50:55 +02:00
.TP
.B \-0, \-\-print0
2018-10-27 17:07:09 +02:00
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
2020-04-09 17:21:40 +02:00
.B \-1
Limit the search to a single result and quit immediately. This is an alias for '--max-results=1'.
.TP
2018-10-27 17:07:09 +02:00
.B \-\-show-errors
Enable the display of filesystem errors for situations such as insufficient
permissions or dead symlinks.
2017-10-17 15:50:55 +02:00
.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
2017-10-17 15:50:55 +02:00
.B \-h, \-\-help
2018-01-03 10:28:34 +01:00
Print help information.
2017-10-17 15:50:55 +02:00
.TP
.B \-V, \-\-version
2018-01-03 10:28:34 +01:00
Print version information.
2017-10-17 15:50:55 +02:00
.TP
2018-01-03 10:28:34 +01:00
.BI "\-d, \-\-max\-depth " d
2017-10-17 15:50:55 +02:00
Limit directory traversal to at most
2018-01-03 10:28:34 +01:00
.I d
levels of depth. By default, there is no limit on the search depth.
2017-10-17 15:50:55 +02:00
.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
2020-10-25 08:16:01 +01:00
.B \-\-prune
Do not traverse into matching directories.
.TP
2017-10-25 21:16:35 +02:00
.BI "\-t, \-\-type " filetype
2017-10-17 15:50:55 +02:00
Filter search by type:
.RS
.IP "f, file"
regular files
.IP "d, directory"
2017-10-17 15:50:55 +02:00
directories
.IP "l, symlink"
2017-10-17 15:50:55 +02:00
symbolic links
2018-03-26 10:25:33 +02:00
.IP "x, executable"
executable (files)
.IP "e, empty"
empty files or directories
.IP "s, socket"
sockets
.IP "p, pipe"
named pipes (FIFOs)
2017-10-17 15:50:55 +02:00
.RE
2018-01-03 10:28:34 +01:00
.RS
This option can be used repeatedly to allow for multiple file types.
.RE
2017-10-17 15:50:55 +02:00
.TP
.BI "\-e, \-\-extension " ext
Filter search results by file extension
.IR ext .
2018-01-03 10:28:34 +01:00
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.
2017-10-25 22:43:36 +02: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.
Examples:
\-\-exclude '*.pyc'
\-\-exclude node_modules
2017-10-17 15:50:55 +02:00
.TP
2018-03-26 10:25:33 +02:00
.BI "\-\-ignore-file " path
Add a custom ignore-file in '.gitignore' format.
These files have a low precedence.
.TP
2017-10-17 15:50:55 +02:00
.BI "\-c, \-\-color " when
Declare
.I when
to colorize search results:
2017-10-17 15:50:55 +02:00
.RS
.IP auto
2017-10-25 21:16:35 +02:00
Colorize output when standard output is connected to terminal (default).
2017-10-17 15:50:55 +02:00
.IP never
Do not colorize output.
2017-10-17 15:50:55 +02:00
.IP always
Always colorize output.
2017-10-17 15:50:55 +02:00
.RE
.TP
.BI "\-j, \-\-threads " num
Set number of threads to use for searching & executing (default: number of available CPU cores).
.TP
2018-08-19 18:50:47 +02: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
.P
If neither '+' nor '-' is specified, file size must be exactly equal to this.
2018-08-19 18:50:47 +02:00
.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)
2018-08-19 18:50:47 +02:00
.IP 'm'
megabytes
.IP 'g'
gigabytes
.IP 't'
terabytes
.IP 'ki'
kibibytes (base two, 2^10 = 1024 bytes)
2018-08-19 18:50:47 +02:00
.IP 'mi'
mebibytes
.IP 'gi'
gibibytes
.IP 'ti'
tebibytes
.RE
.RE
.TP
2018-10-27 17:07:09 +02: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 (\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 "-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
2021-02-03 06:37:36 +01:00
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
2019-02-13 20:04:37 +01:00
.BI "\-x, \-\-exec " command
Execute
.I command
for each search result in parallel (use --threads=1 for sequential command execution). 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
2019-02-13 20:04:37 +01: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 17:11:41 +01:00
.SH PATTERN SYNTAX
2019-11-25 00:13:50 +01:00
The regular expression syntax used by fd is documented here:
https://docs.rs/regex/1.0.0/regex/#syntax
2019-11-25 00:13:50 +01:00
The glob syntax is documented here:
https://docs.rs/globset/#syntax
2017-10-17 15:50:55 +02:00
.SH ENVIRONMENT
.TP
.B LS_COLORS
Determines how to colorize search results, see
.BR dircolors (1) .
2020-04-25 21:32:17 +02:00
.TP
2020-10-24 00:45:32 +02:00
.B NO_COLOR
Disables colorized output.
.TP
2020-04-25 21:32:17 +02:00
.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 .
2017-10-17 15:50:55 +02:00
.SH EXAMPLES
.TP
2017-10-25 21:16:35 +02:00
.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
2017-10-17 15:50:55 +02:00
.TP
.RI "Find all Python files (all files with the extension " .py ") in the current directory:"
2017-10-17 15:50:55 +02:00
$ fd -e py
2019-02-13 20:04:37 +01:00
.TP
.RI "Open all search results with vim:"
$ fd pattern -X vim
2017-10-17 15:50:55 +02:00
.SH SEE ALSO
.BR find (1)