fd

[Tiếng Trung] [한국어]

fdis a program to find entries in your filesystem. It is a simple, fast and user-friendly alternative tofind. While it does not aim to support all offind's powerful functionality, it provides sensible (opinionated) defaults for a majority of use cases.

Installation•How to use•Troubleshooting

Features

• Intuitive syntax:fd PATTERNinstead offind -iname '*PATTERN*'.
• Regular expression (default) and glob-based patterns.
• Very fastdue to parallelized directory traversal.
• Uses colors to highlight different file types (same asls).
• Supportsparallel command execution
• Smart case: the search is case-insensitive by default. It switches to case-sensitive if the pattern contains an uppercase character*.
• Ignores hidden directories and files, by default.
• Ignores patterns from your.gitignore,by default.
• The command name is50%shorter*than find:-).

Demo

How to use

First, to get an overview of all available command line options, you can either run fd -hfor a concise help message orfd --helpfor a more detailed version.

Simple search

fdis designed to find entries in your filesystem. The most basic search you can perform is to runfdwith a single argument: the search pattern. For example, assume that you want to find an old script of yours (the name includednetflix):

>fd netfl
Software/ Python /imdb-ratings/netflix-details.py

If called with just a single argument like this,fdsearches the current directory recursively for any entries thatcontainthe patternnetfl.

Regular expression search

The search pattern is treated as a regular expression. Here, we search for entries that start withxand end withrc:

>cd/etc
>fd'^x.*rc$'
X11/xinit/xinitrc
X11/xinit/xserverrc

The regular expression syntax used byfdisdocumented here.

Specifying the root directory

If we want to search a specific directory, it can be given as a second argument tofd:

>fd passwd /etc
/etc/default/passwd
/etc/pam.d/passwd
/etc/passwd

List all files, recursively

fdcan be called with no arguments. This is very useful to get a quick overview of all entries in the current directory, recursively (similar tols -R):

>cdfd/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^:

>fd.fd/tests/
testenv
testenv/mod.rs
tests.rs

Searching for a particular file extension

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:

>cdfd
>fd -e md
CONTRIBUTING.md
README.md

The-eoption can be used in combination with a search pattern:

>fd -e rs mod
src/fshelper/mod.rs
src/lscolors/mod.rs
tests/testenv/mod.rs

Searching for a particular file name

To find files with exactly the provided search pattern, use the-g(or--glob) option:

>fd -g libc.so /usr
/usr/lib32/libc.so
/usr/lib/libc.so

Hidden and ignored files

By default,fddoes 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:

>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),fddoes not search folders (and does not show files) that match one of the.gitignorepatterns. To disable this behavior, we can use the-I(or--no-ignore) option:

>fd num_cpu
>fd -I num_cpu
target/debug/deps/libnum_cpus-f5ce7ef99006aa05.rlib

To really searchallfiles and directories, simply combine the hidden and ignore features to show everything (-HI) or use-u/--unrestricted.

Matching the full path

By default,fdonly matches the filename of each file. However, using the--full-pathor-poption, you can match against the full path.

>fd -p -g'**/.git/config'
>fd -p'.*/lesson-\d+/[a-z]+.(jpg|png)'

Command execution

Instead of just showing the search results, you often want todo somethingwith them.fd provides two ways to execute external commands for each of your search results:

• The-x/--execoption runs an external commandfor each of the search results(in parallel).
• The-X/--exec-batchoption launches the external command once, withall search results as arguments.

Examples

Recursively find all zip archives and unpack them:

fd -e zip -x unzip

If there are two such files,file1.zipandbackup/file2.zip,this would execute unzip file1.zipandunzip backup/file2.zip.The twounzipprocesses run in parallel (if the files are found fast enough).

Find all*.hand*.cppfiles and auto-format them inplace withclang-format -i:

fd -e h -e cpp -x clang-format -i

Note how the-ioption toclang-formatcan be passed as a separate argument. This is why we put the-xoption last.

Find alltest_*.pyfiles and open them in your favorite editor:

fd -g'test_*.py'-X vim

Note that we use capital-Xhere to open a singleviminstance. If there are two such files, test_basic.pyandlib/test_advanced.py,this will runvim test_basic.py lib/test_advanced.py.

To see details like file permissions, owners, file sizes etc., you can tellfdto show them by runninglsfor each result:

fd… -X ls -lhd --color=always

This pattern is so useful thatfdprovides a shortcut. You can use the-l/--list-details option to executelsin this way:fd… -l.

The-Xoption is also useful when combiningfdwithripgrep(rg) in order to search within a certain class of files, like all C++ source files:

fd -e cpp -e cxx -e h -e hpp -X rg'std::cout'

Convert all*.jpgfiles to*.pngfiles:

fd -e jpg -x convert {} {.}.png

Here,{}is a placeholder for the search result.{.}is the same, without the file extension. See below for more details on the placeholder syntax.

The terminal output of commands run from parallel threads using-xwill not be interlaced or garbled, sofd -xcan be used to rudimentarily parallelize a task run over many files. An example of this is calculating the checksum of each individual file within a directory.

fd -tf -x md5sum > file_checksums.txt

Placeholder syntax

The-xand-Xoptions take acommand templateas a series of arguments (instead of a single string). If you want to add additional options tofdafter the command template, you can terminate it with a\;.

The syntax for generating commands is similar to that ofGNU 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).
• {//}:The parent of the discovered path (documents/images).
• {/.}:The basename, with the extension removed (party).

If you do not include a placeholder,fdautomatically adds a{}at the end.

Parallel vs. serial execution

For-x/--exec,you can control the number of parallel jobs by using the-j/--threadsoption. Use--threads=1for serial execution.

Excluding specific files or directories

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:

>fd -H -E.git…

We can also use this to skip mounted directories:

>fd -E /mnt/external-drive…

.. or to skip certain file types:

>fd -E'*.bak'…

To make exclude-patterns like these permanent, you can create a.fdignorefile. They work like .gitignorefiles, but are specific tofd.For example:

>cat~/.fdignore
/mnt/external-drive
*.bak

Note

fdalso supports.ignorefiles that are used by other programs such asrgorag.

If you wantfdto ignore these patterns globally, you can put them infd's global ignore file. This is usually located in~/.config/fd/ignorein macOS or Linux, and%APPDATA%\fd\ignorein Windows.

You may wish to include.git/in yourfd/ignorefile so that.gitdirectories, and their contents are not included in output if you use the--hiddenoption.

Deleting files

You can usefdto 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/-Xoption to callrm.For example, to recursively remove all.DS_Storefiles, run:

>fd -H'^\.DS_Store$'-tf -X rm

If you are unsure, always callfdwithout-X rmfirst. Alternatively, userms "interactive" option:

>fd -H'^\.DS_Store$'-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 userms--recursive/-rflag to remove directories.

Note

There are scenarios where usingfd… -X rm -rcan cause race conditions: if you have a path like…/foo/bar/foo/…and want to remove all directories namedfoo,you can end up in a situation where the outerfoodirectory is removed first, leading to (harmless)"'foo/bar/foo': No such file or directory"errors in thermcall.

Command-line options

This is the output offd -h.To see the full set of command-line options, usefd --helpwhich also includes a much more detailed help text.

Usage: fd [OPTIONS] [pattern] [path]...

Arguments:
[pattern] the search pattern (a regular expression, unless '--glob' is used; optional)
[path]... the root directories for the filesystem search (optional)

Options:
-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 abs. path (default: filename only)
-d, --max-depth <depth> Set maximum search depth (default: none)
-E, --exclude <pattern> Exclude entries that match the given glob pattern
-t, --type <filetype> Filter by type: file (f), directory (d/dir), symlink (l),
executable (x), empty (e), socket (s), pipe (p), char-device
(c), block-device (b)
-e, --extension <ext> Filter by file extension
-S, --size <size> Limit results based on the size of files
--changed-within <date|dur> Filter by file modification time (newer than)
--changed-before <date|dur> Filter by file modification time (older than)
-o, --owner <user:group> Filter by owning user and/or group
--format <fmt> Print results according to template
-x, --exec <cmd>... Execute a command for each search result
-X, --exec-batch <cmd>... Execute a command with all search results at once
-c, --color <when> When to use colors [default: auto] [possible values: auto,
always, never]
-h, --help Print help (see more with '--help')
-V, --version Print version

Benchmark

Let's search my home folder for files that end in[0-9].jpg.It contains ~750.000 subdirectories and about a 4 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 withfind:

Benchmark 1: find ~ -iregex '.*[0-9]\.jpg$'
Time (mean ± σ): 19.922 s ± 0.109 s
Range (min… max): 19.765 s… 20.065 s

findis much faster if it does not need to perform a regular-expression search:

Benchmark 2: find ~ -iname '*[0-9].jpg'
Time (mean ± σ): 11.226 s ± 0.104 s
Range (min… max): 11.119 s… 11.466 s

Now let's try the same forfd.Note thatfdperforms a regular expression search by default. The options-u/--unrestrictedoption is needed here for a fair comparison. Otherwisefddoes not have to traverse hidden folders and ignored paths (see below):

Benchmark 3: fd -u '[0-9]\.jpg$' ~
Time (mean ± σ): 854.8 ms ± 10.0 ms
Range (min… max): 839.2 ms… 868.9 ms

For this particular example,fdis approximately23 times fasterthanfind -iregex and about13 times fasterthanfind -iname.By the way, both tools found the exact same 546 files 😄.

Note:This isone particularbenchmark onone particularmachine. While we have performed a lot of different tests (and found consistent results), things might be different for you! We encourage everyone to try it out on their own. See this repositoryfor all necessary scripts.

Concerningfd's speed, a lot of credit goes to theregexandignorecrates that are also used inripgrep(check it out!).

Troubleshooting

fddoes not find my file!

Remember thatfdignores hidden directories and files by default. It also ignores patterns from.gitignorefiles. If you want to make sure to find absolutely every possible file, always use the options-u/--unrestrictedoption (or-HIto enable hidden and ignored files):

>fd -u…

Colorized output

fdcan colorize files by extension, just likels.In order for this to work, the environment variableLS_COLORShas to be set. Typically, the value of this variable is set by thedircolorscommand which provides a convenient configuration format to define colors for different file formats. On most distributions,LS_COLORSshould be set already. If you are on Windows or if you are looking for alternative, more complete (or more colorful) variants, seehere, hereor here.

fdalso honors theNO_COLORenvironment variable.

fddoesn't seem to interpret my regex pattern correctly

A 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:

>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:

>fd --'-pattern'
>fd'[-]pattern'

"Command not found" foraliases or shell functions

Shellaliases and shell functions can not be used for command execution viafd -xor fd -X.Inzsh,you can make the alias global viaalias -g myalias= "…".Inbash, you can useexport -f my_functionto make available to child processes. You would still need to callfd -x bash -c 'my_function "$1" ' bash.For other use cases or shells, use a (temporary) shell script.

Integration with other programs

Using fd withfzf

You can usefdto generate input for the command-line fuzzy finderfzf:

exportFZF_DEFAULT_COMMAND='fd --type file'
exportFZF_CTRL_T_COMMAND="$FZF_DEFAULT_COMMAND"

Then, you can typevim <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.gitfolders):

exportFZF_DEFAULT_COMMAND='fd --type file --follow --hidden --exclude.git'

You can even use fd's colored output inside fzf by setting:

exportFZF_DEFAULT_COMMAND="fd --type file --color=always"
exportFZF_DEFAULT_OPTS="--ansi"

For more details, see theTips sectionof the fzf README.

Using fd withrofi

rofiis a graphical launch menu application that is able to create menus by reading fromstdin.Pipingfdoutput intorofis-dmenumode creates fuzzy-searchable lists of files and directories.

Example

Create a case-insensitive searchable multi-select list ofPDFfiles under your$HOMEdirectory and open the selection with your configured PDF viewer. To list all file types, drop the-e pdfargument.

fd --type f -e pdf.$HOME|rofi -keep-right -dmenu -i -p FILES -multi-select|xargs -I {} xdg-open {}

To modify the list that is presented by rofi, add arguments to thefdcommand. To modify the search behaviour of rofi, add arguments to theroficommand.

Using fd withemacs

The emacs packagefind-file-in-projectcan usefdto find files.

After installingfind-file-in-project,add the line(setq ffip-use-rust-fd t)to your ~/.emacsor~/.emacs.d/init.elfile.

In emacs, runM-x find-file-in-project-by-selectedto find matching files. Alternatively, run M-x find-file-in-projectto list all available files in the project.

Printing the output as a tree

To format the output offdas a file-tree you can use thetreecommand with --fromfile:

❯ fd|tree --fromfile

This can be more useful than runningtreeby itself becausetreedoes not ignore any files by default, nor does it support as rich a set of options as fddoes to control what to print:

❯ fd --extension rs|tree --fromfile
.
├── build.rs
└── src
├── app.rs
└── error.rs

On bash and similar you can simply create an alias:

❯aliasas-tree='tree --fromfile'

Using fd withxargsorparallel

Note thatfdhas a builtin feature forcommand executionwith its-x/--execand-X/--exec-batchoptions. If you prefer, you can still use it in combination withxargs:

>fd -0 -e rs|xargs -0 wc -l

Here, the-0option tellsfdto separate search results by the NULL character (instead of newlines). In the same way, the-0option ofxargstells it to read the input in this way.

Installation

On Ubuntu

... and other Debian-based Linux distributions.

If you run Ubuntu 19.04 (Disco Dingo) or newer, you can install the officially maintained package:

apt install fd-find

Note that the binary is calledfdfindas the binary namefdis already used by another package. It is recommended that after installation, you add a link tofdby executing command ln -s $(which fdfind) ~/.local/bin/fd,in order to usefdin the same way as in this documentation. Make sure that$HOME/.local/binis in your$PATH.

If you use an older version of Ubuntu, you can download the latest.debpackage from the release pageand install it via:

dpkg -i fd_9.0.0_amd64.deb#adapt version number and architecture

Note that the.deb packages on the release page for this project still name the executablefd.

On Debian

If you run Debian Buster or newer, you can install the officially maintained Debian package:

apt-get install fd-find

Note that the binary is calledfdfindas the binary namefdis already used by another package. It is recommended that after installation, you add a link tofdby executing command ln -s $(which fdfind) ~/.local/bin/fd,in order to usefdin the same way as in this documentation. Make sure that$HOME/.local/binis in your$PATH.

Note that the.deb packages on the release page for this project still name the executablefd.

On Fedora

Starting with Fedora 28, you can installfdfrom the official package sources:

dnf install fd-find

On Alpine Linux

You can installthe fd package from the official sources, provided you have the appropriate repository enabled:

apk add fd

On Arch Linux

You can installthe fd packagefrom the official repos:

pacman -S fd

You can also install fdfrom the AUR.

On Gentoo Linux

You can usethe fd ebuildfrom the official repo:

emerge -av fd

On openSUSE Linux

You can installthe fd packagefrom the official repo:

zypper in fd

On Void Linux

You can installfdvia xbps-install:

xbps-install -S fd

On ALT Linux

You can installthe fd packagefrom the official repo:

apt-get install fd

On Solus

You can installthe fd packagefrom the official repo:

eopkg install fd

On RedHat Enterprise Linux 8/9 (RHEL8/9), Almalinux 8/9, EuroLinux 8/9 or Rocky Linux 8/9

You can installthefdpackagefrom Fedora Copr.

dnf coprenabletkbcopr/fd
dnf install fd

A different version using theslowermallocinstead of jemallocis also available from the EPEL8/9 repo as the packagefd-find.

On macOS

You can installfdwithHomebrew:

brew install fd

…or with MacPorts:

port install fd

On Windows

You can download pre-built binaries from therelease page.

Alternatively, you can installfdviaScoop:

scoop install fd

Or viaChocolatey:

choco install fd

Or viaWinget:

winget install sharkdp.fd

On GuixOS

You can installthe fd packagefrom the official repo:

guix install fd

On NixOS / via Nix

You can use theNix package managerto installfd:

nix-env -i fd

Via Flox

You can useFloxto installfdinto a Flox environment:

flox install fd

On FreeBSD

You can installthe fd-find packagefrom the official repo:

pkg install fd-find

From npm

On Linux and macOS, you can install thefd-findpackage:

npm install -g fd-find

From source

With Rust's package managercargo,you can installfdvia:

cargo install fd-find

Note that rust version1.77.2or later is required.

makeis also needed for the build.

From binaries

Therelease pageincludes precompiled binaries for Linux, macOS and Windows. Statically-linked binaries are also available: look for archives withmuslin the file name.

Development

git clone https://github /sharkdp/fd

#Build
cdfd
cargo build

#Run unit tests and integration tests
cargotest

#Install
cargo install --path.

Maintainers

• sharkdp
• tmccombs
• tavianator

License

fdis distributed under the terms of both the MIT License and the Apache License 2.0.

See theLICENSE-APACHEandLICENSE-MITfiles for license details.