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 By default fd uses regular expressions for the pattern. However, this
16 can be changed to use simple glob patterns with the '--glob' option.
17
19 -H, --hidden
20 Include hidden files and directories in the search results (de‐
21 fault: hidden files and directories are skipped). The flag can
22 be overridden with '--no-hidden'.
23 -I, --no-ignore
25 Show search results from files and directories that would other‐
26 wise be ignored by
27 • .gitignore
29 • .git/info/exclude
31 • The global gitignore configuration (by default $HOME/.con‐
33 fig/git/ignore)
34 • .ignore
36 • .fdignore
38 • The global fd ignore file (usually $HOME/.config/fd/ignore )
40 The flag can be overridden with '--ignore'.
42 -u, --unrestricted
44 Perform an unrestricted search, including ignored and hidden
45 files. This is an alias for '--hidden --no-ignore'.
46 --no-ignore-vcs
48 Show search results from files and directories that would other‐
49 wise be ignored by gitignore files including .gitignore,
50 .git/info/exclude, and the global gitignore configuration
51 (core.excludesFile git setting, which defaults to $HOME/.con‐
52 fig/git/ignore). The flag can be overridden with '--ignore-
53 vcs'.
54 --no-require-git
56 Do not require a git repository to respect gitignores. By de‐
57 fault, fd will only respect global gitignore rules, .gitignore
58 rules and local exclude rules if fd detects that you are search‐
59 ing inside a git repository. This flag allows you to relax this
60 restriction such that fd will respect all git related ignore
61 rules regardless of whether you’re searching in a git repository
62 or not. The flag can be overridden with '--require-git'.
63 --no-ignore-parent
65 Show search results from files and directories that would other‐
66 wise be ignored by gitignore files in parent directories.
67 -s, --case-sensitive
69 Perform a case-sensitive search. By default, fd uses case-insen‐
70 sitive searches, unless the pattern contains an uppercase char‐
71 acter (smart case).
72 -i, --ignore-case
74 Perform a case-insensitive search. By default, fd uses case-in‐
75 sensitive searches, unless the pattern contains an uppercase
76 character (smart case).
77 -g, --glob
79 Perform a glob-based search instead of a regular expression
80 search. If combined with the '--full-path' option, '**' can be
81 used to match multiple path components.
82 --regex
84 Perform a regular-expression based search (default). This can be
85 used to override --glob.
86 -F, --fixed-strings
88 Treat the pattern as a literal string instead of a regular ex‐
89 pression. Note that this also performs substring comparison. If
90 you want to match on an exact filename, consider using '--glob'.
91 --and pattern
93 Add additional required search patterns, all of which must be
94 matched. Multiple additional patterns can be specified. The pat‐
95 terns are regular expressions, unless '--glob' or
96 '--fixed-strings' is used.
97 -a, --absolute-path
99 Shows the full path starting from the root as opposed to rela‐
100 tive paths. The flag can be overridden with '--relative-path'.
101 -l, --list-details
103 Use a detailed listing format like 'ls -l'. This is basically an
104 alias for '--exec-batch ls -l' with some additional 'ls' op‐
105 tions. This can be used to see more metadata, to show symlink
106 targets and to achieve a deterministic sort order.
107 -L, --follow
109 By default, fd does not descend into symlinked directories. Us‐
110 ing this flag, symbolic links are also traversed. The flag can
111 be overridden with '--no-follow'.
112 -p, --full-path
114 By default, the search pattern is only matched against the file‐
115 name (or directory name). Using this flag, the pattern is
116 matched against the full path.
117 -0, --print0
119 Separate search results by the null character (instead of new‐
120 lines). Useful for piping results to xargs.
121 --max-results count
123 Limit the number of search results to 'count' and quit immedi‐
124 ately.
125 -1 Limit the search to a single result and quit immediately. This
127 is an alias for '--max-results=1'.
128 -q, --quiet
130 When the flag is present, the program does not print anything
131 and will instead exit with a code of 0 if there is at least one
132 search result. Otherwise, the exit code will be 1. This is
133 mainly for usage in scripts and can be faster than checking for
134 output because the search can be stopped early after the first
135 match. --has-results can be used as an alias.
136 --show-errors
138 Enable the display of filesystem errors for situations such as
139 insufficient permissions or dead symlinks.
140 --strip-cwd-prefix
142 By default, relative paths are prefixed with './' when the out‐
143 put goes to a non interactive terminal (TTY). Use this flag to
144 disable this behaviour.
145 --one-file-system, --mount, --xdev
147 By default, fd will traverse the file system tree as far as
148 other options dictate. With this flag, fd ensures that it does
149 not descend into a different file system than the one it started
150 in. Comparable to the -mount or -xdev filters of find(1).
151 -h, --help
153 Print help information.
154 -V, --version
156 Print version information.
157 -d, --max-depth d
159 Limit directory traversal to at most d levels of depth. By de‐
160 fault, there is no limit on the search depth.
161 --min-depth d
163 Only show search results starting at the given depth. See also:
164 '--max-depth' and '--exact-depth'.
165 --exact-depth d
167 Only show search results at the exact given depth. This is an
168 alias for '--min-depth <depth> --max-depth <depth>'.
169 --prune
171 Do not traverse into matching directories.
172 -t, --type filetype
174 Filter search by type:
175 f, file
177 regular files
178 d, directory
180 directories
181 l, symlink
183 symbolic links
184 s, socket
186 sockets
187 p, pipe
189 named pipes (FIFOs)
190 x, executable
192 executable (files)
193 e, empty
195 empty files or directories
196 This option can be specified more than once to include multiple
198 file types. Searching for '--type file --type symlink' will
199 show both regular files as well as symlinks. Note that the 'exe‐
200 cutable' and 'empty' filters work differently: '--type exe‐
201 cutable' implies '--type file' by default. And '--type empty'
202 searches for empty files and directories, unless either '--type
203 file' or '--type directory' is specified in addition.
204 Examples:
206 - Only search for files:
207 fd --type file …
208 fd -tf …
209 - Find both files and symlinks
210 fd --type file --type symlink …
211 fd -tf -tl …
212 - Find executable files:
213 fd --type executable
214 fd -tx
215 - Find empty files:
216 fd --type empty --type file
217 fd -te -tf
218 - Find empty directories:
219 fd --type empty --type directory
220 fd -te -td
221 -e, --extension ext
223 Filter search results by file extension ext. This option can be
224 used repeatedly to allow for multiple possible file extensions.
225 If you want to search for files without extension, you can use
227 the regex '^[^.]+$' as a normal search pattern.
228 -E, --exclude pattern
230 Exclude files/directories that match the given glob pattern.
231 This overrides any other ignore logic. Multiple exclude pat‐
232 terns can be specified. Examples:
233 --exclude '*.pyc'
234 --exclude node_modules
235 --ignore-file path
237 Add a custom ignore-file in '.gitignore' format. These files
238 have a low precedence.
239 -c, --color when
241 Declare when to colorize search results:
242 auto Colorize output when standard output is connected to ter‐
244 minal (default).
245 never Do not colorize output.
247 always Always colorize output.
249 -j, --threads num
251 Set number of threads to use for searching & executing (default:
252 number of available CPU cores).
253 -S, --size size
255 Limit results based on the size of files using the format
256 <+-><NUM><UNIT>
257 '+' file size must be greater than or equal to this
259 '-' file size must be less than or equal to this
261 If neither '+' nor '-' is specified, file size must be exactly
263 equal to this.
264 'NUM' The numeric size (e.g. 500)
266 'UNIT' The units for NUM. They are not case-sensitive. Allowed
268 unit values:
269 'b' bytes
271 'k' kilobytes (base ten, 10^3 = 1000 bytes)
273 'm' megabytes
275 'g' gigabytes
277 't' terabytes
279 'ki' kibibytes (base two, 2^10 = 1024 bytes)
281 'mi' mebibytes
283 'gi' gibibytes
285 'ti' tebibytes
287 --changed-within date|duration
289 Filter results based on the file modification time. Files with
290 modification times greater than the argument will be returned.
291 The argument can be provided as a duration (10h, 1d, 35min) or
292 as a specific point in time in either full RFC3339 format with
293 time zone, or as a date or datetime in the local time zone
294 (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS). --change-newer-than,
295 --newer or --changed-after can be used as aliases.
296 Examples:
298 --changed-within 2weeks
299 --change-newer-than "2018-10-27 10:00:00"
300 --newer 2018-10-27
301 --changed-before date|duration
303 Filter results based on the file modification time. Files with
304 modification times less than the argument will be returned. The
305 argument can be provided as a duration (10h, 1d, 35min) or as a
306 specific point in time in either full RFC3339 format with time
307 zone, or as a date or datetime in the local time zone (YYYY-MM-
308 DD or YYYY-MM-DD HH:MM:SS). --change-older-than or --older can
309 be used as aliases.
310 Examples:
312 --changed-before "2018-10-27 10:00:00"
313 --change-older-than 2weeks
314 -o, --owner [user][:group]
316 Filter files by their user and/or group. Format:
317 [(user|uid)][:(group|gid)]. Either side is optional. Precede ei‐
318 ther side with a '!' to exclude files instead.
319 Examples:
321 --owner john
322 --owner :students
323 --owner "!john:students"
324 --base-directory path
326 Change the current working directory of fd to the provided path.
327 This means that search results will be shown with respect to the
328 given base path. Note that relative paths which are passed to fd
329 via the positional path argument or the --search-path option
330 will also be resolved relative to this directory.
331 --path-separator separator
333 Set the path separator to use when printing file paths. The de‐
334 fault is the OS-specific separator ('/' on Unix, '\' on Win‐
335 dows).
336 --search-path search-path
338 Provide paths to search as an alternative to the positional path
339 argument. Changes the usage to ´fd [FLAGS/OPTIONS] --search-path
340 PATH --search-path PATH2 [PATTERN]´
341 -x, --exec command
343 Execute command for each search result in parallel (use
344 --threads=1 for sequential command execution).
345 Note that all subsequent positional arguments are considered to
347 be arguments to the command - not to fd. It is therefore recom‐
348 mended to place the -x/--exec option last. Alternatively, you
349 can supply a ';' argument to end the argument list and continue
350 with more fd options. Most shells require ';' to be escaped:
351 '\;'. This option can be specified multiple times, in which
352 case all commands are run for each file found, in the order they
353 are provided. In that case, you must supply a ';' argument for
354 all but the last commands.
355 The following placeholders are substituted before the command is
357 executed:
358 {} path (of the current search result)
360 {/} basename
362 {//} parent directory
364 {.} path without file extension
366 {/.} basename without file extension
368 If no placeholder is present, an implicit "{}" at the end is as‐
370 sumed.
371 Examples:
373 - find all *.zip files and unzip them:
375 fd -e zip -x unzip
377 - find *.h and *.cpp files and run "clang-format -i .." for
379 each of them:
380 fd -e h -e cpp -x clang-format -i
382 - Convert all *.jpg files to *.png files:
384 fd -e jpg -x convert {} {.}.png
386 -X, --exec-batch command
388 Execute command once, with all search results as arguments. One
389 of the following placeholders is substituted before the command
390 is executed:
391 {} path (of all search results)
393 {/} basename
395 {//} parent directory
397 {.} path without file extension
399 {/.} basename without file extension
401 If no placeholder is present, an implicit "{}" at the end is as‐
403 sumed.
404 Like --exec, this can be used multiple times, in which case each
406 command will be run in the order given.
407 Examples:
409 - Find all test_*.py files and open them in your favorite edi‐
411 tor:
412 fd -g 'test_*.py' -X vim
414 Note that this executes a single "vim" process with all
416 search results as arguments.
417 - Find all *.rs files and count the lines with "wc -l ...":
419 fd -e rs -X wc -l
421 --batch-size size
423 Maximum number of arguments to pass to the command given with
424 -X. If the number of results is greater than the given size, the
425 command given with -X is run again with remaining arguments. A
426 batch size of zero means there is no limit (default), but note
427 that batching might still happen due to OS restrictions on the
428 maximum length of command lines.
429
431 The regular expression syntax used by fd is documented here:
432 https://docs.rs/regex/1.0.0/regex/#syntax
434 The glob syntax is documented here:
436 https://docs.rs/globset/#syntax
438
440 LS_COLORS
441 Determines how to colorize search results, see dircolors(1).
442 NO_COLOR
444 Disables colorized output.
445 XDG_CONFIG_HOME, HOME
447 Used to locate the global ignore file. If XDG_CONFIG_HOME is
448 set, use $XDG_CONFIG_HOME/fd/ignore. Otherwise, use $HOME/.con‐
449 fig/fd/ignore.
450
452 Find files and directories that match the pattern 'needle':
453 $ fd needle
454 Start a search in a given directory (/var/log):
456 $ fd nginx /var/log
457 Find all Python files (all files with the extension .py) in the current
459 directory:
460 $ fd -e py
461 Open all search results with vim:
463 $ fd pattern -X vim
464
466 Bugs can be reported on GitHub: https://github.com/sharkdp/fd/issues
467
469 find(1)
470 FD(1)