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 (de‐
18 fault: 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-in‐
40 sensitive 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 search (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 ex‐
53 pression. Note that this also performs substring comparison. If
54 you want to match on an exact filename, consider using '--glob'.
55 -a, --absolute-path
57 Shows the full path starting from the root as opposed to rela‐
58 tive paths.
59 -l, --list-details
61 Use a detailed listing format like 'ls -l'. This is basically an
62 alias for '--exec-batch ls -l' with some additional 'ls' op‐
63 tions. This can be used to see more metadata, to show symlink
64 targets and to achieve a deterministic sort order.
65 -L, --follow
67 By default, fd does not descend into symlinked directories. Us‐
68 ing this flag, symbolic links are also traversed.
69 -p, --full-path
71 By default, the search pattern is only matched against the file‐
72 name (or directory name). Using this flag, the pattern is
73 matched against the full path.
74 -0, --print0
76 Separate search results by the null character (instead of new‐
77 lines). Useful for piping results to xargs.
78 --max-results count
80 Limit the number of search results to 'count' and quit immedi‐
81 ately.
82 -1 Limit the search to a single result and quit immediately. This
84 is an alias for '--max-results=1'.
85 --show-errors
87 Enable the display of filesystem errors for situations such as
88 insufficient permissions or dead symlinks.
89 --one-file-system, --mount, --xdev
91 By default, fd will traverse the file system tree as far as
92 other options dictate. With this flag, fd ensures that it does
93 not descend into a different file system than the one it started
94 in. Comparable to the -mount or -xdev filters of find(1).
95 -h, --help
97 Print help information.
98 -V, --version
100 Print version information.
101 -d, --max-depth d
103 Limit directory traversal to at most d levels of depth. By de‐
104 fault, there is no limit on the search depth.
105 --min-depth d
107 Only show search results starting at the given depth. See also:
108 '--max-depth' and '--exact-depth'.
109 --exact-depth d
111 Only show search results at the exact given depth. This is an
112 alias for '--min-depth <depth> --max-depth <depth>'.
113 --prune
115 Do not traverse into matching directories.
116 -t, --type filetype
118 Filter search by type:
119 f, file
121 regular files
122 d, directory
124 directories
125 l, symlink
127 symbolic links
128 x, executable
130 executable (files)
131 e, empty
133 empty files or directories
134 s, socket
136 sockets
137 p, pipe
139 named pipes (FIFOs)
140 This option can be used repeatedly to allow for multiple file
142 types.
143 -e, --extension ext
145 Filter search results by file extension ext. This option can be
146 used repeatedly to allow for multiple possible file extensions.
147 If you want to search for files without extension, you can use
149 the regex '^[^.]+$' as a normal search pattern.
150 -E, --exclude pattern
152 Exclude files/directories that match the given glob pattern.
153 This overrides any other ignore logic. Multiple exclude pat‐
154 terns can be specified. Examples:
155 --exclude '*.pyc'
156 --exclude node_modules
157 --ignore-file path
159 Add a custom ignore-file in '.gitignore' format. These files
160 have a low precedence.
161 -c, --color when
163 Declare when to colorize search results:
164 auto Colorize output when standard output is connected to ter‐
166 minal (default).
167 never Do not colorize output.
169 always Always colorize output.
171 -j, --threads num
173 Set number of threads to use for searching & executing (default:
174 number of available CPU cores).
175 -S, --size size
177 Limit results based on the size of files using the format
178 <+-><NUM><UNIT>
179 '+' file size must be greater than or equal to this
181 '-' file size must be less than or equal to this
183 If neither '+' nor '-' is specified, file size must be exactly
185 equal to this.
186 'NUM' The numeric size (e.g. 500)
188 'UNIT' The units for NUM. They are not case-sensitive. Allowed
190 unit values:
191 'b' bytes
193 'k' kilobytes (base ten, 10^3 = 1000 bytes)
195 'm' megabytes
197 'g' gigabytes
199 't' terabytes
201 'ki' kibibytes (base two, 2^10 = 1024 bytes)
203 'mi' mebibytes
205 'gi' gibibytes
207 'ti' tebibytes
209 --changed-within date|duration
211 Filter results based on the file modification time. The argument
212 can be provided as a specific point in time (YYYY-MM-DD
213 HH:MM:SS) or as a duration (10h, 1d, 35min). --change-newer-
214 than can be used as an alias.
215 Examples:
217 --changed-within 2weeks
218 --change-newer-than "2018-10-27 10:00:00"
219 --changed-before date|duration
221 Filter results based on the file modification time. The argument
222 can be provided as a specific point in time (YYYY-MM-DD
223 HH:MM:SS) or as a duration (10h, 1d, 35min). --change-older-
224 than can be used as an alias.
225 Examples:
227 --changed-before "2018-10-27 10:00:00"
228 --change-older-than 2weeks
229 -o, --owner [user][:group]
231 Filter files by their user and/or group. Format:
232 [(user|uid)][:(group|gid)]. Either side is optional. Precede ei‐
233 ther side with a '!' to exclude files instead.
234 Examples:
236 --owner john
237 --owner :students
238 --owner "!john:students"
239 --base-directory path
241 Change the current working directory of fd to the provided path.
242 This means that search results will be shown with respect to the
243 given base path. Note that relative paths which are passed to fd
244 via the positional path argument or the --search-path option
245 will also be resolved relative to this directory.
246 --path-separator separator
248 Set the path separator to use when printinf file paths. The de‐
249 fault is the OS-specific separator ('/' on Unix, '\' on Win‐
250 dows).
251 --search-path search-path
253 Provide paths to search as an alternative to the positional path
254 argument. Changes the usage to ´fd [FLAGS/OPTIONS] --search-path
255 PATH --search-path PATH2 [PATTERN]´
256 -x, --exec command
258 Execute command for each search result. The following placehold‐
259 ers are substituted by a path derived from the current search
260 result:
261 {} path
263 {/} basename
265 {//} parent directory
267 {.} path without file extension
269 {/.} basename without file extension
271 -X, --exec-batch command
273 Execute command with all search results at once. A single oc‐
274 curence of the following placeholders is authorized and substi‐
275 tuted by the paths derived from the search results before the
276 command is executed:
277 {} path
279 {/} basename
281 {//} parent directory
283 {.} path without file extension
285 {/.} basename without file extension
287
289 The regular expression syntax used by fd is documented here:
290 https://docs.rs/regex/1.0.0/regex/#syntax
292 The glob syntax is documented here:
294 https://docs.rs/globset/#syntax
296
298 LS_COLORS
299 Determines how to colorize search results, see dircolors(1).
300 NO_COLOR
302 Disables colorized output.
303 XDG_CONFIG_HOME, HOME
305 Used to locate the global ignore file. If XDG_CONFIG_HOME is
306 set, use $XDG_CONFIG_HOME/fd/ignore. Otherwise, use $HOME/.con‐
307 fig/fd/ignore.
308
310 Find files and directories that match the pattern 'needle':
311 $ fd needle
312 Start a search in a given directory (/var/log):
314 $ fd nginx /var/log
315 Find all Python files (all files with the extention .py) in the current
317 directory:
318 $ fd -e py
319 Open all search results with vim:
321 $ fd pattern -X vim
322
324 find(1)
325 FD(1)