1FD(1) General Commands Manual FD(1)
2
6 fd - find entries in the filesystem
7
9 fd [-HIEsiaLp0hV] [-d depth] [-t filetype] [-e ext] [-E exclude] [-c
10 when] [-j num] [-x cmd] [pattern] [path...]
11
13 fd is a simple, fast and user-friendly alternative to find(1).
14
16 -H, --hidden
17 Include hidden files and directories in the search results
18 (default: hidden files and directories are skipped).
19 -I, --no-ignore
21 Show search results from files and directories that would other‐
22 wise be ignored by .gitignore, .ignore, .fdignore, or the global
23 ignore file.
24 -u, --unrestricted
26 Alias for '--no-ignore'. Can be repeated; '-uu' is an alias for
27 '--no-ignore --hidden'.
28 --no-ignore-vcs
30 Show search results from files and directories that would other‐
31 wise be ignored by .gitignore files.
32 -s, --case-sensitive
34 Perform a case-sensitive search. By default, fd uses case-insen‐
35 sitive searches, unless the pattern contains an uppercase char‐
36 acter (smart case).
37 -i, --ignore-case
39 Perform a case-insensitive search. By default, fd uses case-
40 insensitive searches, unless the pattern contains an uppercase
41 character (smart case).
42 -g, --glob
44 Perform a glob-based search instead of a regular expression
45 search.
46 --regex
48 Perform a regular-expression based seach (default). This can be
49 used to override --glob.
50 -F, --fixed-strings
52 Treat the pattern as a literal string instead of a regular
53 expression.
54 -a, --absolute-path
56 Shows the full path starting from the root as opposed to rela‐
57 tive paths.
58 -l, --list-details
60 Use a detailed listing format like 'ls -l'. This is basically an
61 alias for '--exec-batch ls -l' with some additional 'ls'
62 options. This can be used to see more metadata, to show symlink
63 targets and to achieve a deterministic sort order.
64 -L, --follow
66 By default, fd does not descend into symlinked directories.
67 Using this flag, symbolic links are also traversed.
68 -p, --full-path
70 By default, the search pattern is only matched against the file‐
71 name (or directory name). Using this flag, the pattern is
72 matched against the full path.
73 -0, --print0
75 Separate search results by the null character (instead of new‐
76 lines). Useful for piping results to xargs.
77 --max-results count
79 Limit the number of search results to 'count' and quit immedi‐
80 ately.
81 -1 Limit the search to a single result and quit immediately. This
83 is an alias for '--max-results=1'.
84 --show-errors
86 Enable the display of filesystem errors for situations such as
87 insufficient permissions or dead symlinks.
88 --one-file-system, --mount, --xdev
90 By default, fd will traverse the file system tree as far as
91 other options dictate. With this flag, fd ensures that it does
92 not descend into a different file system than the one it started
93 in. Comparable to the -mount or -xdev filters of find(1).
94 -h, --help
96 Print help information.
97 -V, --version
99 Print version information.
100 -d, --max-depth d
102 Limit directory traversal to at most d levels of depth. By
103 default, there is no limit on the search depth.
104 --min-depth d
106 Only show search results starting at the given depth. See also:
107 '--max-depth' and '--exact-depth'.
108 --exact-depth d
110 Only show search results at the exact given depth. This is an
111 alias for '--min-depth <depth> --max-depth <depth>'.
112 -t, --type filetype
114 Filter search by type:
115 f, file
117 regular files
118 d, directory
120 directories
121 l, symlink
123 symbolic links
124 x, executable
126 executable (files)
127 e, empty
129 empty files or directories
130 s, socket
132 sockets
133 p, pipe
135 named pipes (FIFOs)
136 This option can be used repeatedly to allow for multiple file
138 types.
139 -e, --extension ext
141 Filter search results by file extension ext. This option can be
142 used repeatedly to allow for multiple possible file extensions.
143 -E, --exclude pattern
145 Exclude files/directories that match the given glob pattern.
146 This overrides any other ignore logic. Multiple exclude pat‐
147 terns can be specified.
148 --ignore-file path
150 Add a custom ignore-file in '.gitignore' format. These files
151 have a low precedence.
152 -c, --color when
154 Declare when to colorize search results:
155 auto Colorize output when standard output is connected to ter‐
157 minal (default).
158 never Do not colorize output.
160 always Always colorize output.
162 -j, --threads num
164 Set number of threads to use for searching & executing (default:
165 number of available CPU cores).
166 -S, --size size
168 Limit results based on the size of files using the format
169 <+-><NUM><UNIT>
170 '+' file size must be greater than or equal to this
172 '-' file size must be less than or equal to this
174 'NUM' The numeric size (e.g. 500)
176 'UNIT' The units for NUM. They are not case-sensitive. Allowed
178 unit values:
179 'b' bytes
181 'k' kilobytes (base ten, 10^3 = 1000 bytes)
183 'm' megabytes
185 'g' gigabytes
187 't' terabytes
189 'ki' kibibytes (base two, 2^10 = 1024 bytes)
191 'mi' mebibytes
193 'gi' gibibytes
195 'ti' tebibytes
197 --changed-within date|duration
199 Filter results based on the file modification time. The argument
200 can be provided as a specific point in time (YYYY-MM-DD
201 HH:MM:SS) or as a duration (10h, 1d, 35min). --change-newer-
202 than can be used as an alias.
203 Examples:
205 --changed-within 2weeks
206 --change-newer-than "2018-10-27 10:00:00"
207 --changed-before date|duration
209 Filter results based on the file modification time. The argument
210 can be provided as a specific point in time (YYYY-MM-DD
211 HH:MM:SS) or as a duration (10h, 1d, 35min). --change-older-
212 than can be used as an alias.
213 Examples:
215 --changed-before "2018-10-27 10:00:00"
216 --change-older-than 2weeks
217 -o, --owner [user][:group]
219 Filter files by their user and/or group. Format:
220 [(user|uid)][:(group|gid)]. Either side is optional. Precede
221 either side with a '!' to exclude files instead.
222 Examples:
224 --owner john
225 --owner :students
226 --owner "!john:students"
227 -x, --exec command
229 Execute command for each search result. The following placehold‐
230 ers are substituted by a path derived from the current search
231 result:
232 {} path
234 {/} basename
236 {//} parent directory
238 {.} path without file extension
240 {/.} basename without file extension
242 -X, --exec-batch command
244 Execute command with all search results at once. A single
245 occurence of the following placeholders is authorized and sub‐
246 stituted by the paths derived from the search results before the
247 command is executed:
248 {} path
250 {/} basename
252 {//} parent directory
254 {.} path without file extension
256 {/.} basename without file extension
258
260 The regular expression syntax used by fd is documented here:
261 ⟨https://docs.rs/regex/1.0.0/regex/#syntax⟩
263 The glob syntax is documented here:
265 ⟨https://docs.rs/globset/#syntax⟩
267
269 LS_COLORS
270 Determines how to colorize search results, see dircolors(1).
271 XDG_CONFIG_HOME, HOME
273 Used to locate the global ignore file. If XDG_CONFIG_HOME is
274 set, use $XDG_CONFIG_HOME/fd/ignore. Otherwise, use $HOME/.con‐
275 fig/fd/ignore.
276
278 Find files and directories that match the pattern 'needle':
279 $ fd needle
280 Start a search in a given directory (/var/log):
282 $ fd nginx /var/log
283 Find all Python files (all files with the extention .py) in the current
285 directory:
286 $ fd -e py
287 Open all search results with vim:
289 $ fd pattern -X vim
290
292 find(1)
293 FD(1)