fd
5 min read
fd is a program to find entries in your filesystem. It is a simple, fast and user-friendly alternative to find. While it does not aim to support all of find's powerful functionality, it provides sensible (opinionated) defaults for a majority of use cases.
Usage
Usage: fd [OPTIONS] [pattern] [path]...
Options
| Option | Description |
|---|---|
-H, --hidden | Include hidden directories and files in the search results |
-I, --no-ignore | Show search results from files and directories that would otherwise be ignored by .gitignore, .ignore, .fdignore |
-u, --unrestricted | Perform an unrestricted search, including ignored and hidden files. This is an alias for --no-ignore --hidden. |
-s, --case-sensitive | Perform a case-sensitive search. By default, fd uses case-insensitive searches, unless the pattern contains an uppercase character (smart case). |
-i, --ignore-case | Perform a case-insensitive search. By default, fd uses case-insensitive searches, unless the pattern contains an uppercase character (smart case). |
-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. |
-L, --follow | By default, fd does not descend into symlinked directories. Using this flag, symbolic links are also traversed. Flag can be overriden with --no-follow. |
-0, --print0 | Separate search results by the null character (instead of newlines). Useful for piping results to xargs. |
-d, --max-depth <depth> | Limit the directory traversal to a given depth. By default, there is no limit on the search depth. |
--min-depth <depth> | Only show search results starting at the given depth. |
--exact-depth <depth> | Only show search results at the exact given depth. This is an alias for --min-depth <depth> --max-depth <depth>. |
-E, --exclude <pattern> | Exclude files/directories that match the given glob pattern. This overrides any other ignore logic. Multiple exclude patterns can be specified. |
-t, --type <filetype> | Filter the search by type:<br>- f or file: regular files<br>- d or directory: directories<br>- l or symlink: symbolic links<br>- s or socket: socket<br>- p or pipe: named pipe (FIFO)<br>- x or executable: executables<br>- e or empty: empty files or directories<br><br>This option can be specified more than once to include multiple file types. |
-e, --extension <ext> | (Additionally) filter search results by their file extension. Multiple allowable file extensions can be specified. |
-S, --size <size> | Limit results based on the size of files using the format <+-><NUM><UNIT>.<br>- +: file size must be greater than or equal to this<br>- -: file size must be less than or equal to this<br>If neither + nor - is specified, file size must be exactly equal to this. |
--changed-within <date/dur> | Filter results based on the file modification time. Files with modification times greater than the argument are returned. The argument can be provided as a specific point in time (YYYY-MM-DD HH:MM:SS) or as a duration (10h, 1d, 35min). If the time is not specified, it defaults to 00:00:00. --change-newer-than, --newer, or --changed-after can be used as aliases.<br><br>Examples:<br>- --changed-within 2weeks<br>- --change-newer-than '2018-10-27 10:00:00'<br>- --newer 2018-10-27<br>- --changed-after 1day |
--changed-before <date/dur> | Filter results based on the file modification time. Files with modification times less than the argument are returned. |
-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.<br><br>Examples:<br>- --owner john<br>- --owner :students<br>- --owner '!john:students' |
-x, --exec <cmd>... | Execute a command for each search result in parallel (use --threads=1 for sequential command execution). All positional arguments following --exec are considered to be arguments to the command - not to fd. It is therefore recommended to place the -x/--exec option last.<br><br>The following placeholders are substituted before the command is executed:<br>- {}: path (of the current search result)<br>- {/}: basename<br>- {//}: parent directory<br>- {.}: path without file extension<br>- {/.}: basename without file extension<br><br>If no placeholder is present, an implicit {} at the end is assumed. |
-X, --exec-batch <cmd>... | Execute the given command once, with all search results as arguments. One of the following placeholders is substituted before the command is executed:<br><br>- {}: path (of all search results)<br>- {/}: basename<br>- {//}: parent directory<br>- {.}: path without file extension<br>- {/.}: basename without file extension<br><br>If no placeholder is present, an implicit {} at the end is assumed. |
--batch-size <size> | Maximum number of arguments to pass to the command given with -X. If the number of results is greater than the given size, the command given with -X is run again with remaining arguments. A batch size of zero means there is no limit (default), but note that batching might still happen due to OS restrictions on the maximum length of command lines. |
--ignore-file <path> | Add a custom ignore-file in .gitignore format. These files have a low precedence. |
-j, --threads <num> | Set number of threads to use for searching & executing (default: number of available CPU cores) |
--max-results <count> | Limit the number of search results to count and quit immediately. |
-1 | Limit the search to a single result and quit immediately. This is an alias for --max-results=1. |
-q, --quiet | When the flag is present, the program does not print anything and will return with an exit code of 0 if there is at least one match. Otherwise, the exit code will be 1. |
--one-file-system | 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. |