中文
한국어fd is a simple, fast and user-friendly alternative to find.
While it does not seek to mirror all of find's powerful functionality, it provides sensible (opinionated) defaults for 80% of the use cases.
fd PATTERN instead of find -iname '*PATTERN*'..gitignore, by default.find :-).
Let's search my home folder for files that end in [0-9].jpg. It contains ~190.000
subdirectories and about a million files. For averaging and statistical analysis, I'm using
hyperfine. The following benchmarks are performed
with a "warm"/pre-filled disk-cache (results for a "cold" disk-cache show the same trends).
Let's start with find:
```
Benchmark #1: find ~ -iregex '.*[0-9].jpg$'
Time (mean ± σ): 7.236 s ± 0.090 s
Range (min … max): 7.133 s … 7.385 s ```
find is much faster if it does not need to perform a regular-expression search:
```
Benchmark #2: find ~ -iname '*[0-9].jpg'
Time (mean ± σ): 3.914 s ± 0.027 s
Range (min … max): 3.876 s … 3.964 s ```
Now let's try the same for fd. Note that fd always performs a regular expression
search. The options --hidden and --no-ignore are needed for a fair comparison,
otherwise fd does not have to traverse hidden folders and ignored paths (see below):
```
Benchmark #3: fd -HI '.*[0-9].jpg$' ~
Time (mean ± σ): 811.6 ms ± 26.9 ms
Range (min … max): 786.0 ms … 870.7 ms
``
For this particular example,fdis approximately nine times faster thanfind -iregex
and about five times faster thanfind -iname`. By the way, both tools found the exact
same 20880 files :smile:.
Finally, let's run fd without --hidden and --no-ignore (this can lead to different
search results, of course). If fd does not have to traverse the hidden and git-ignored
folders, it is almost an order of magnitude faster:
```
Benchmark #4: fd '[0-9].jpg$' ~
Time (mean ± σ): 123.7 ms ± 6.0 ms
Range (min … max): 118.8 ms … 140.0 ms ```
Note: This is one particular benchmark on one particular machine. While I have performed quite a lot of different tests (and found consistent results), things might be different for you! I encourage everyone to try it out on their own. See this repository for all necessary scripts.
Concerning fd's speed, the main credit goes to the regex and ignore crates that are also used
in ripgrep (check it out!).
fd can colorize files by extension, just like ls. In order for this to work, the environment
variable LS_COLORS has to be set. Typically, the value
of this variable is set by the dircolors command which provides a convenient configuration format
to define colors for different file formats.
On most distributions, LS_COLORS should be set already. If you are on Windows or if you are looking
for alternative, more complete (or more colorful) variants, see here,
here or
here.
fd also honors the NO_COLOR environment variable.
If the -x/--exec option is specified alongside a command template, a job pool will be created
for executing commands in parallel for each discovered path as the input. The syntax for generating
commands is similar to that of GNU Parallel:
{}: A placeholder token that will be replaced with the path of the search result
(documents/images/party.jpg).{.}: Like {}, but without the file extension (documents/images/party).{/}: A placeholder that will be replaced by the basename of the search result (party.jpg).{//}: Uses the parent of the discovered path (documents/images).{/.}: Uses the basename, with the extension removed (party).``` bash
fd -e jpg -x convert {} {.}.png
fd -e zip -x unzip
fd -e flac -x ffmpeg -i {} -c:a libopus {.}.opus
fd -x wc -l \; -e rs ```
The number of threads used for command execution can be set with the --threads/-j option.
```
USAGE:
fd [FLAGS/OPTIONS] [
FLAGS: -H, --hidden Search hidden files and directories -I, --no-ignore Do not respect .(git|fd)ignore files -s, --case-sensitive Case-sensitive search (default: smart case) -i, --ignore-case Case-insensitive search (default: smart case) -g, --glob Glob-based search (default: regular expression) -a, --absolute-path Show absolute instead of relative paths -l, --list-details Use a long listing format with file metadata -L, --follow Follow symbolic links -p, --full-path Search full path (default: file-/dirname only) -0, --print0 Separate results by the null character -h, --help Prints help information -V, --version Prints version information
OPTIONS:
-d, --max-depth
ARGS:
This is the output of fd -h. To see the full set of command-line options, use fd --help which
also includes a much more detailed help text.
First, to get an overview of all available command line options, you can either run
fd -h for a concise help message (see above) or fd --help for a more detailed
version.
fd is designed to find entries in your filesystem. The most basic search you can perform is to
run fd with a single argument: the search pattern. For example, assume that you want to find an
old script of yours (the name included netflix):
``` bash
fd netfl Software/python/imdb-ratings/netflix-details.py ``
If called with just a single argument like this, *fd* searches the current directory recursively for any entries that *contain* the patternnetfl`.
The search pattern is treated as a regular expression. Here, we search for entries that start
with x and end with rc:
``` bash
cd /etc fd '^x.*rc$' X11/xinit/xinitrc X11/xinit/xserverrc ```
The regular expression syntax used by fd is documented here:
https://docs.rs/regex/1.0.0/regex/#syntax
If we want to search a specific directory, it can be given as a second argument to fd: ``` bash
fd passwd /etc /etc/default/passwd /etc/pam.d/passwd /etc/passwd ```
fd can be called with no arguments. This is very useful to get a quick overview of all entries
in the current directory, recursively (similar to ls -R):
``` bash
cd fd/tests fd testenv testenv/mod.rs tests.rs ```
If you want to use this functionality to list all files in a given directory, you have to use
a catch-all pattern such as . or ^:
``` bash
fd . fd/tests/ testenv testenv/mod.rs tests.rs ```
Often, we are interested in all files of a particular type. This can be done with the -e (or
--extension) option. Here, we search for all Markdown files in the fd repository:
``` bash
cd fd fd -e md CONTRIBUTING.md README.md ```
The -e option can be used in combination with a search pattern:
``` bash
fd -e rs mod src/fshelper/mod.rs src/lscolors/mod.rs tests/testenv/mod.rs ```
By default, fd does not search hidden directories and does not show hidden files in the
search results. To disable this behavior, we can use the -H (or --hidden) option:
``` bash
fd pre-commit fd -H pre-commit .git/hooks/pre-commit.sample ```
If we work in a directory that is a Git repository (or includes Git repositories), fd does not
search folders (and does not show files) that match one of the .gitignore patterns. To disable
this behavior, we can use the -I (or --no-ignore) option:
``` bash
fd numcpu fd -I numcpu target/debug/deps/libnum_cpus-f5ce7ef99006aa05.rlib ```
To really search all files and directories, simply combine the hidden and ignore features to show
everything (-HI).
Sometimes we want to ignore search results from a specific subdirectory. For example, we might
want to search all hidden files and directories (-H) but exclude all matches from .git
directories. We can use the -E (or --exclude) option for this. It takes an arbitrary glob
pattern as an argument:
``` bash
fd -H -E .git … ```
We can also use this to skip mounted directories: ``` bash
fd -E /mnt/external-drive … ```
.. or to skip certain file types: ``` bash
fd -E '*.bak' … ```
To make exclude-patterns like these permanent, you can create a .fdignore file. They work like
.gitignore files, but are specific to fd. For example:
``` bash
cat ~/.fdignore /mnt/external-drive *.bak ``
Note:fdalso supports.ignorefiles that are used by other programs such asrgorag`.
If you want fd to ignore these patterns globally, you can put them in fd's global ignore file.
This is usually located in ~/.config/fd/ignore in macOS or Linux, and %APPDATA%\fd\ignore in
Windows.
xargs or parallelIf we want to run a command on all search results, we can pipe the output to xargs:
``` bash
fd -0 -e rs | xargs -0 wc -l ``
Here, the-0option tells *fd* to separate search results by the NULL character (instead of newlines). In the same way, the-0option ofxargs` tells it to read the input in this way.
You can use fd to remove all files and directories that are matched by your search pattern.
If you only want to remove files, you can use the --exec-batch/-X option to call rm. For
example, to recursively remove all .DS_Store files, run:
``` bash
fd -H '^.DSStore$' -tf -X rm
If you are unsure, always call `fd` without `-X rm` first. Alternatively, use `rm`s "interactive" option:bash fd -H '^.DSStore$' -tf -X rm -i ```
If you also want to remove a certain class of directories, you can use the same technique. You will
have to use rms --recursive/-r flag to remove directories.
Note: there are scenarios where using fd … -X rm -r can cause race conditions: if you have a
path like …/foo/bar/foo/… and want to remove all directories named foo, you can end up in a
situation where the outer foo directory is removed first, leading to (harmless) "'foo/bar/foo':
No such file or directory" errors in the rm call.
fd does not find my file!Remember that fd ignores hidden directories and files by default. It also ignores patterns
from .gitignore files. If you want to make sure to find absolutely every possible file, always
use the options -H and -I to disable these two features:
``` bash
fd -HI … ```
fd doesn't seem to interpret my regex pattern correctlyA lot of special regex characters (like [], ^, $, ..) are also special characters in your
shell. If in doubt, always make sure to put single quotes around the regex pattern:
``` bash
fd '^[A-Z][0-9]+$' ```
If your pattern starts with a dash, you have to add -- to signal the end of command line
options. Otherwise, the pattern will be interpreted as a command-line option. Alternatively,
use a character class with a single hyphen character:
``` bash
fd -- '-pattern' fd '[-]pattern' ```
fzfYou can use fd to generate input for the command-line fuzzy finder fzf:
bash
export FZF_DEFAULT_COMMAND='fd --type file'
export FZF_CTRL_T_COMMAND="$FZF_DEFAULT_COMMAND"
Then, you can type vim <Ctrl-T> on your terminal to open fzf and search through the fd-results.
Alternatively, you might like to follow symbolic links and include hidden files (but exclude .git folders):
bash
export FZF_DEFAULT_COMMAND='fd --type file --follow --hidden --exclude .git'
You can even use fd's colored output inside fzf by setting:
bash
export FZF_DEFAULT_COMMAND="fd --type file --color=always"
export FZF_DEFAULT_OPTS="--ansi"
For more details, see the Tips section of the fzf README.
emacsThe emacs package find-file-in-project can use fd to find files.
After installing find-file-in-project, add the line (setq ffip-use-rust-fd t) to your
~/.emacs or ~/.emacs.d/init.el file.
In emacs, run M-x find-file-in-project-by-selected to find matching files. Alternatively, run
M-x find-file-in-project to list all available files in the project.
To format the output of fd similar to the tree command, install [as-tree] and pipe the output
of fd to as-tree:
bash
fd | as-tree
This can be more useful than running tree by itself because tree does not ignore any files by
default, nor does it support as rich a set of options as fd does to control what to print:
bash
❯ fd --extension rs | as-tree
.
├── build.rs
└── src
├── app.rs
└── error.rs
For more information about as-tree, see [the as-tree README][as-tree].
... and other Debian-based Linux distributions.
If you run Ubuntu 19.04 (Disco Dingo) or newer, you can install the
officially maintained package:
sudo apt install fd-find
Note that the binary is called fdfind as the binary name fd is already used by another package.
It is recommended that you add an alias fd=fdfind to your shells initialization file, in order to
use fd in the same way as in this documentation.
If you use an older version of Ubuntu, you can download the latest .deb package from the
release page and install it via:
bash
sudo dpkg -i fd_8.2.1_amd64.deb # adapt version number and architecture
If you run Debian Buster or newer, you can install the
officially maintained Debian package:
sudo apt-get install fd-find
Note that the binary is called fdfind as the binary name fd is already used by another package.
It is recommended that you add an alias fd=fdfind to your shells initialization file, in order to
use fd in the same way as in this documentation.
Starting with Fedora 28, you can install fd from the official package sources:
bash
dnf install fd-find
For older versions, you can use this Fedora copr to install fd:
bash
dnf copr enable keefle/fd
dnf install fd
You can install the fd package
from the official sources, provided you have the appropriate repository enabled:
apk add fd
You can install the fd package from the official repos:
pacman -S fd
You can use the fd ebuild from the official repo:
emerge -av fd
You can install the fd package from the official repo:
zypper in fd
You can install fd via xbps-install:
xbps-install -S fd
You can install fd with Homebrew:
brew install fd
… or with MacPorts:
sudo port install fd
You can download pre-built binaries from the release page.
Alternatively, you can install fd via Scoop:
scoop install fd
Or via Chocolatey:
choco install fd
You can use the Nix package manager to install fd:
nix-env -i fd
You can install the fd-find package from the official repo:
pkg install fd-find
On linux and macOS, you can install the fd-find package:
npm install -g fd-find
With Rust's package manager cargo, you can install fd via:
cargo install fd-find
Note that rust version 1.36.0 or later is required.
The release page includes precompiled binaries for Linux, macOS and Windows.
```bash git clone https://github.com/sharkdp/fd
cd fd cargo build
cargo test
cargo install --path . ```
Copyright (c) 2017-2020 The fd developers
fd is distributed under the terms of both the MIT License and the Apache License 2.0.
See the LICENSE-APACHE and LICENSE-MIT files for license details.