2017-05-12 11:50:03 +02:00
# fd
2017-05-12 14:16:34 +02:00
[![Build Status ](https://travis-ci.org/sharkdp/fd.svg?branch=master )](https://travis-ci.org/sharkdp/fd)
2017-09-27 21:47:41 +02:00
[![Build status ](https://ci.appveyor.com/api/projects/status/21c4p5fwggc5gy3j?svg=true )](https://ci.appveyor.com/project/sharkdp/fd)
2017-09-17 13:17:40 +02:00
[![Version info ](https://img.shields.io/crates/v/fd-find.svg )](https://crates.io/crates/fd-find)
2017-05-12 14:16:34 +02:00
2017-06-02 20:34:02 +02:00
*fd* is a simple, fast and user-friendly alternative to
[*find* ](https://www.gnu.org/software/findutils/ ).
2017-05-13 10:21:38 +02:00
2017-06-02 20:34:02 +02:00
While it does not seek to mirror all of *find* 's powerful functionality, it provides sensible
(opinionated) defaults for [80% ](https://en.wikipedia.org/wiki/Pareto_principle ) of the use cases.
2017-05-09 23:45:02 +02:00
2017-05-12 14:16:34 +02:00
## Features
* Convenient syntax: `fd PATTERN` instead of `find -iname '*PATTERN*'` .
2017-09-09 18:29:11 +02:00
* Colorized terminal output (similar to *ls* ).
2017-10-08 20:54:54 +02:00
* It's *fast* (see [benchmarks ](#benchmark ) below).
2017-05-13 10:21:38 +02:00
* Smart case: the search is case-insensitive by default. It switches to
case-sensitive if the pattern contains an uppercase
character[\*](http://vimdoc.sourceforge.net/htmldoc/options.html#'smartcase').
2017-06-02 20:42:55 +02:00
* Ignores hidden directories and files, by default.
* Ignores patterns from your `.gitignore` , by default.
* Regular expressions.
* Unicode-awareness.
2017-06-02 20:34:02 +02:00
* The command name is *50%* shorter[\*](https://github.com/ggreer/the_silver_searcher) than
`find` :-).
2017-10-14 18:04:11 +02:00
* Parallel command execution with a syntax similar to GNU Parallel.
2017-05-09 23:29:14 +02:00
2017-05-13 00:05:00 +02:00
## Demo
2017-05-13 00:07:32 +02:00
2018-01-28 13:32:26 +01:00
![Demo ](doc/screencast.svg )
2017-05-09 23:35:34 +02:00
2017-05-13 10:46:22 +02:00
## Benchmark
2018-02-10 16:43:36 +01:00
Let's search my home folder for files that end in `[0-9].jpg` . It contains ~190.000
2017-09-09 18:29:11 +02:00
subdirectories and about a million files. For averaging and statistical analysis, I'm using
2018-02-10 16:43:36 +01:00
[hyperfine ](https://github.com/sharkdp/hyperfine ). The following benchmarks are performed
with a "warm"/pre-filled disk-cache (results for a "cold" disk-cache show the same trends).
2017-09-09 18:29:11 +02:00
Let's start with `find` :
2017-10-14 22:42:47 +02:00
```
2018-02-10 16:43:36 +01:00
Benchmark #1: find ~ -iregex '.*[0-9]\.jpg$'
2017-09-09 18:29:11 +02:00
2018-02-10 16:43:36 +01:00
Time (mean ± σ ): 7.236 s ± 0.090 s
Range (min … max): 7.133 s … 7.385 s
2017-09-09 18:29:11 +02:00
```
`find` is much faster if it does not need to perform a regular-expression search:
2017-10-14 22:42:47 +02:00
```
2018-02-10 16:43:36 +01:00
Benchmark #2: find ~ -iname '*[0-9].jpg'
2017-05-13 10:46:22 +02:00
2018-02-10 16:43:36 +01:00
Time (mean ± σ ): 3.914 s ± 0.027 s
Range (min … max): 3.876 s … 3.964 s
2017-09-09 18:29:11 +02:00
```
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):
2017-10-14 22:42:47 +02:00
```
2018-02-10 16:43:36 +01:00
Benchmark #3: fd -HI '.*[0-9]\.jpg$' ~
2017-09-09 18:29:11 +02:00
2018-02-10 16:43:36 +01:00
Time (mean ± σ ): 811.6 ms ± 26.9 ms
Range (min … max): 786.0 ms … 870.7 ms
2017-09-09 18:29:11 +02:00
```
2018-02-10 16:43:36 +01:00
For this particular example, `fd` is approximately nine times faster than `find -iregex`
and about five times faster than `find -iname` . By the way, both tools found the exact
same 20880 files :smile:.
2017-09-09 18:29:11 +02:00
Finally, let's run `fd` without `--hidden` and `--no-ignore` (this can lead to different
2018-02-10 16:43:36 +01:00
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:
2017-10-14 22:42:47 +02:00
```
2018-02-10 16:43:36 +01:00
Benchmark #4: fd '[0-9]\.jpg$' ~
2017-09-09 18:29:11 +02:00
2018-02-10 16:43:36 +01:00
Time (mean ± σ ): 123.7 ms ± 6.0 ms
Range (min … max): 118.8 ms … 140.0 ms
2017-05-13 10:46:22 +02:00
```
2017-06-09 15:04:40 +02:00
2017-09-09 18:29:11 +02:00
**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
2018-02-10 16:43:36 +01:00
be different for you! I encourage everyone to try it out on their own. See
[this repository ](https://github.com/sharkdp/fd-benchmarks ) for all necessary scripts.
2017-05-13 10:46:22 +02:00
2017-09-09 18:29:11 +02:00
Concerning *fd* 's speed, the main credit goes to the `regex` and `ignore` crates that are also used
in [ripgrep ](https://github.com/BurntSushi/ripgrep ) (check it out!).
2017-09-09 17:07:19 +02:00
2017-10-08 20:54:54 +02:00
## Colorized output
`fd` can colorize files by extension, just like `ls` . In order for this to work, the environment
variable [`LS_COLORS` ](https://linux.die.net/man/5/dir_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 ](https://github.com/seebi/dircolors-solarized ) or
[here ](https://github.com/trapd00r/LS_COLORS ).
2017-10-22 21:57:20 +02:00
## 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:
- `{}` : 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
2017-11-15 03:19:28 +01:00
# Convert all jpg files to png files:
fd -e jpg -x convert {} {.}.png
2017-10-22 21:57:20 +02:00
# 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:
2017-11-15 03:19:28 +01:00
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
2017-10-14 18:04:11 +02:00
```
2018-01-01 15:27:05 +01:00
## Installation
2017-11-16 08:19:20 +01:00
2018-01-01 15:27:05 +01:00
### On Ubuntu
2018-01-10 13:02:25 +01:00
*... and other Debian-based Linux distributions.*
2017-11-16 08:19:20 +01:00
2018-01-01 15:27:05 +01:00
Download the latest `.deb` package from the [release page ](https://github.com/sharkdp/fd/releases ) and install it via:
``` bash
2018-03-26 10:16:18 +02:00
sudo dpkg -i fd_7.0.0_amd64.deb # adapt version number and architecture
2017-05-14 20:07:59 +02:00
```
2018-01-01 15:27:05 +01:00
2018-03-14 21:12:16 +01:00
### On Fedora
You can use this [fedora copr ](https://copr.fedorainfracloud.org/coprs/keefle/fd/ ) to install `fd` :
```
dnf copr enable keefle/fd
dnf install fd
```
2018-01-01 15:27:05 +01:00
### On Arch Linux
2018-02-11 11:41:54 +01:00
You can install [the fd package ](https://www.archlinux.org/packages/community/x86_64/fd/ ) from the official repos:
2018-01-01 15:27:05 +01:00
```
2018-02-11 11:41:54 +01:00
pacman -S fd
2017-05-14 20:07:59 +02:00
```
2018-02-19 01:18:57 +01:00
### On Gentoo Linux
You can use [the fd ebuild ](https://packages.gentoo.org/packages/sys-apps/fd ) from the official repo:
```
emerge -av fd
```
2017-05-13 10:46:22 +02:00
2018-03-31 19:38:55 +02:00
### On openSUSE Linux
You can install [the fd package ](https://software.opensuse.org/package/fd ) from the official repo:
```
zypper in fd
```
2018-01-01 15:27:05 +01:00
### On Void Linux
2017-11-16 08:19:20 +01:00
2018-01-01 15:27:05 +01:00
You can install `fd` via xbps-install:
```
xbps-install -S fd
```
2017-11-16 08:19:20 +01:00
### On macOS
You can install [this Homebrew package ](http://braumeister.org/formula/fd ):
2017-06-15 12:25:16 +02:00
```
brew install fd
```
2018-01-01 15:27:05 +01:00
### On Windows
2017-11-16 08:19:20 +01:00
2018-01-01 15:27:05 +01:00
You can download pre-built binaries from the [release page ](https://github.com/sharkdp/fd/releases ).
2017-08-01 03:44:29 +02:00
2018-02-24 12:07:24 +01:00
Alternatively, you can install `fd` via [Scoop ](http://scoop.sh ):
2018-02-23 06:02:45 +01:00
```
scoop install fd
```
2018-03-16 03:43:07 +01:00
Or via [Chocolatey ](https://chocolatey.org ):
```
choco install fd
```
2017-11-16 08:19:20 +01:00
### On NixOS / via Nix
You can use the [Nix package manager ](https://nixos.org/nix/ ) to install `fd` :
2017-10-14 21:33:24 +02:00
```
nix-env -i fd
```
2018-01-01 15:27:05 +01:00
### On FreeBSD
2017-10-07 16:18:19 +02:00
2017-11-16 08:19:20 +01:00
You can install `sysutils/fd` via portmaster:
2017-11-15 21:30:58 +01:00
```
portmaster sysutils/fd
```
2018-01-01 15:27:05 +01:00
### From source
2017-11-16 15:50:19 +01:00
2018-01-01 15:27:05 +01:00
With Rust's package manager [cargo ](https://github.com/rust-lang/cargo ), you can install *fd* via:
2017-11-16 15:50:19 +01:00
```
2018-01-01 15:27:05 +01:00
cargo install fd-find
2017-11-16 15:50:19 +01:00
```
2018-01-01 15:27:05 +01:00
Note that rust version *1.20.0* or later is required.
### From binaries
The [release page ](https://github.com/sharkdp/fd/releases ) includes precompiled binaries for Linux, macOS and Windows.
2017-11-16 15:50:19 +01:00
2017-05-14 20:07:59 +02:00
## Development
2017-05-09 23:29:14 +02:00
```bash
2017-09-09 18:56:03 +02:00
git clone https://github.com/sharkdp/fd
# Build
cd fd
cargo build
2017-10-07 16:19:47 +02:00
# Run unit tests and integration tests
2017-09-09 18:56:03 +02:00
cargo test
# Install
cargo install
2017-05-09 23:29:14 +02:00
```
2017-09-09 19:32:30 +02:00
## Command-line options
```
USAGE:
2017-12-10 06:40:13 +01:00
fd [FLAGS/OPTIONS] [< pattern > ] [< path > ...]
2017-09-09 19:32:30 +02:00
FLAGS:
-H, --hidden Search hidden files and directories
2018-03-26 10:25:33 +02:00
-I, --no-ignore Do not respect .(git|fd)ignore files
2017-12-10 06:40:13 +01:00
--no-ignore-vcs Do not respect .gitignore files
2017-10-03 20:23:53 +02:00
-s, --case-sensitive Case-sensitive search (default: smart case)
2017-10-22 11:47:05 +02:00
-i, --ignore-case Case-insensitive search (default: smart case)
2018-02-10 15:19:53 +01:00
-F, --fixed-strings Treat the pattern as a literal string
2017-09-09 19:32:30 +02:00
-a, --absolute-path Show absolute instead of relative paths
2017-10-03 20:23:53 +02:00
-L, --follow Follow symbolic links
-p, --full-path Search full path (default: file-/dirname only)
-0, --print0 Separate results by the null character
2017-09-09 19:32:30 +02:00
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
2018-03-26 10:25:33 +02:00
-d, --max-depth < depth > Set maximum search depth (default: none)
-t, --type < filetype > ... Filter by type: file (f), directory (d), symlink (l),
executable (x)
-e, --extension < ext > ... Filter by file extension
-x, --exec < cmd > Execute a command for each search result
-E, --exclude < pattern > ... Exclude entries that match the given glob pattern
--ignore-file < path > ... Add a custom ignore-file in .gitignore format
-c, --color < when > When to use colors: never, *auto* , always
-j, --threads < num > Set number of threads to use for searching & executing
2017-09-09 19:32:30 +02:00
ARGS:
< pattern > the search pattern, a regular expression (optional)
2017-12-10 06:40:13 +01:00
< path > ... the root directory for the filesystem search (optional)
2017-09-09 19:32:30 +02:00
```
2017-10-06 16:31:04 +02:00
2017-10-06 17:07:26 +02:00
## Tutorial
2017-10-06 16:31:04 +02:00
2017-10-22 19:16:49 +02:00
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.
2017-10-06 16:31:04 +02:00
2017-10-22 19:16:49 +02:00
### Simple search
2017-10-15 22:27:02 +02:00
2017-10-22 19:16:49 +02:00
*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
2017-10-15 22:27:02 +02:00
```
2017-10-22 19:16:49 +02:00
If called with just a single argument like this, *fd* searches the current directory recursively
for any entries that *contain* the pattern `netfl` .
2017-10-15 22:27:02 +02:00
2017-10-22 19:16:49 +02:00
### Regular expression search
2017-10-06 16:31:04 +02:00
2017-10-22 19:16:49 +02:00
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
2017-10-06 16:31:04 +02:00
```
2017-10-22 19:16:49 +02:00
### Specifying the root directory
2017-10-06 16:31:04 +02:00
2018-01-10 13:02:25 +01:00
If we want to search a specific directory, it can be given as a second argument to *fd* :
2017-10-22 19:16:49 +02:00
``` bash
> fd passwd /etc
/etc/default/passwd
/etc/pam.d/passwd
/etc/passwd
2017-10-15 22:27:02 +02:00
```
2017-10-22 19:16:49 +02:00
### Running *fd* without any arguments
2017-10-06 16:31:04 +02:00
2017-10-22 19:16:49 +02:00
*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
2017-10-06 16:31:04 +02:00
```
2017-10-22 19:16:49 +02:00
### Searching for a particular file extension
2017-10-06 16:31:04 +02:00
2017-10-22 19:16:49 +02:00
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
2017-10-06 16:31:04 +02:00
```
2017-10-22 19:16:49 +02:00
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
2017-10-06 16:31:04 +02:00
```
2017-10-22 19:16:49 +02:00
### 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
2017-10-06 16:31:04 +02:00
```
2017-10-22 19:16:49 +02:00
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
2018-02-09 14:35:58 +01:00
this behavior, we can use the `-I` (or `--no-ignore` ) option:
2017-10-22 19:16:49 +02:00
``` bash
> fd num_cpu
> fd -I num_cpu
target/debug/deps/libnum_cpus-f5ce7ef99006aa05.rlib
2017-10-06 16:31:04 +02:00
```
2017-10-22 19:16:49 +02:00
To really search *all* files and directories, simply combine the hidden and ignore features to show
everything (`-HI`).
2017-10-15 22:27:02 +02:00
2018-03-13 22:54:08 +01:00
### 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
```
2017-10-22 19:16:49 +02:00
### Using fd with `xargs` or `parallel`
2017-10-15 22:27:02 +02:00
2017-10-22 19:16:49 +02:00
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
2017-10-06 16:31:04 +02:00
```
2018-03-13 22:34:19 +01:00
Here, the `-0` option tells *fd* to separate search results by the NULL character (instead of
newlines). In the same way, the `-0` option of `xargs` tells it to read the input in this way.
2018-01-02 22:26:38 +01:00
2018-04-12 16:17:00 +02:00
### Integration with other programs
#### Using fd with `fzf`
2018-01-02 22:26:38 +01:00
You can use *fd* to generate input for the command-line fuzzy finder [fzf ](https://github.com/junegunn/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 ](https://github.com/junegunn/fzf#tips ) of the fzf README.
2018-04-12 16:17:00 +02:00
#### Using fd with `emacs`
Emacs package [find-file-in-project ](https://github.com/technomancy/find-file-in-project ) can use *fd* to find files in project.
Setup in simple. After installing `find-file-in-project` , you only insert one line `(setq ffip-use-rust-fd t)` into `~/.emacs` or `~/.emacs.d/init.el` .
No further setup is required and it should work out of box on Window/Linux/Mac.
In Emacs, please run `M-x find-file-in-project-by-selected` to find files matching glob pattern.
Or run `M-x find-file-in-project` to list all available file in project.