fd

Build Status Build status Version info

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.

Features

Demo

Demo

Benchmark

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!).

Colorized output

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 looking for alternative, more complete (and more colorful) variants, see here or here.

Parallel command execution

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:

``` bash

Convert all jpg files to png files:

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

Unpack all zip files (if no placeholder is given, the path is appended):

fd -e zip -x unzip

Convert all flac files into opus files:

fd -e flac -x ffmpeg -i {} -c:a libopus {.}.opus

Count the number of lines in Rust files (the command template can be terminated with ';'):

fd -x wc -l \; -e rs ```

Installation

On Ubuntu

... and other Debian-based Linux distributions.

Download the latest .deb package from the release page and install it via: bash sudo dpkg -i fd_7.0.0_amd64.deb # adapt version number and architecture

On Fedora

You can use this fedora copr to install fd: dnf copr enable keefle/fd dnf install fd

On Arch Linux

You can install the fd package from the official repos: pacman -S fd

On Gentoo Linux

You can use the fd ebuild from the official repo: emerge -av fd

On Void Linux

You can install fd via xbps-install: xbps-install -S fd

On macOS

You can install this Homebrew package: brew install fd

On Windows

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

On NixOS / via Nix

You can use the Nix package manager to install fd: nix-env -i fd

On FreeBSD

You can install sysutils/fd via portmaster: portmaster sysutils/fd

From source

With Rust's package manager cargo, you can install fd via: cargo install fd-find Note that rust version 1.20.0 or later is required.

From binaries

The release page includes precompiled binaries for Linux, macOS and Windows.

Development

```bash git clone https://github.com/sharkdp/fd

Build

cd fd cargo build

Run unit tests and integration tests

cargo test

Install

cargo install ```

Command-line options

``` USAGE: fd [FLAGS/OPTIONS] [] [...]

FLAGS: -H, --hidden Search hidden files and directories -I, --no-ignore Do not respect .(git|fd)ignore files --no-ignore-vcs Do not respect .gitignore files -s, --case-sensitive Case-sensitive search (default: smart case) -i, --ignore-case Case-insensitive search (default: smart case) -F, --fixed-strings Treat the pattern as a literal string -a, --absolute-path Show absolute instead of relative paths -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 Set maximum search depth (default: none) -t, --type ... Filter by type: file (f), directory (d), symlink (l), executable (x) -e, --extension ... Filter by file extension -x, --exec Execute a command for each search result -E, --exclude ... Exclude entries that match the given glob pattern --ignore-file ... Add a custom ignore-file in .gitignore format -c, --color When to use colors: never, auto, always -j, --threads Set number of threads to use for searching & executing

ARGS: the search pattern, a regular expression (optional) ... the root directory for the filesystem search (optional) ```

Tutorial

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.

Simple search

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`.

Regular expression search

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

Specifying the root directory

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

Running fd without any arguments

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

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

Hidden and ignored files

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).

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

Using fd with xargs or parallel

If 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.

Using fd with fzf

You 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.