fd/README.md

121 lines
4.7 KiB
Markdown
Raw Normal View History

2017-05-12 09:50:03 +00:00
# fd
2017-05-12 12:16:34 +00:00
[![Build Status](https://travis-ci.org/sharkdp/fd.svg?branch=master)](https://travis-ci.org/sharkdp/fd)
2017-06-02 18:34:02 +00:00
*fd* is a simple, fast and user-friendly alternative to
[*find*](https://www.gnu.org/software/findutils/).
2017-05-13 08:21:38 +00:00
2017-06-02 18:34:02 +00: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 21:45:02 +00:00
2017-05-12 12:16:34 +00:00
## Features
* Convenient syntax: `fd PATTERN` instead of `find -iname '*PATTERN*'`.
2017-09-09 16:29:11 +00:00
* Colorized terminal output (similar to *ls*).
* It's *fast* (see benchmarks below).
2017-05-13 08:21:38 +00: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 18:42:55 +00:00
* Ignores hidden directories and files, by default.
* Ignores patterns from your `.gitignore`, by default.
* Regular expressions.
* Unicode-awareness.
2017-06-02 18:34:02 +00:00
* The command name is *50%* shorter[\*](https://github.com/ggreer/the_silver_searcher) than
`find` :-).
2017-05-09 21:29:14 +00:00
2017-05-12 22:05:00 +00:00
## Demo
2017-05-12 22:07:32 +00:00
2017-05-14 19:58:52 +00:00
![Demo](http://i.imgur.com/iU6qkQj.gif)
2017-05-09 21:35:34 +00:00
2017-05-14 18:18:17 +00:00
## Colorized output
2017-06-02 18:34:02 +00:00
`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
2017-05-14 18:18:17 +00:00
[here](https://github.com/seebi/dircolors-solarized) or
[here](https://github.com/trapd00r/LS_COLORS).
2017-05-13 08:46:22 +00:00
## Benchmark
2017-09-09 16:29:11 +00:00
Let's search my home folder for files that end in `[0-9].jpg`. It contains ~150.000
subdirectories and about a million files. For averaging and statistical analysis, I'm using
[bench](https://github.com/Gabriel439/bench). All benchmarks are performed for a "warm
cache". Results for a cold cache are similar.
Let's start with `find`:
2017-06-09 13:04:40 +00:00
```
2017-09-09 16:29:11 +00:00
find ~ -iregex '.*[0-9]\.jpg$'
time 6.265 s (6.127 s .. NaN s)
2017-06-09 13:04:40 +00:00
1.000 R² (1.000 R² .. 1.000 R²)
2017-09-09 16:29:11 +00:00
mean 6.162 s (6.140 s .. 6.181 s)
std dev 31.73 ms (0.0 s .. 33.48 ms)
```
`find` is much faster if it does not need to perform a regular-expression search:
```
find ~ -iname '*[0-9].jpg'
2017-05-13 08:46:22 +00:00
2017-09-09 16:29:11 +00:00
time 2.866 s (2.754 s .. 2.964 s)
2017-06-09 13:04:40 +00:00
1.000 R² (0.999 R² .. 1.000 R²)
2017-09-09 16:29:11 +00:00
mean 2.860 s (2.834 s .. 2.875 s)
std dev 23.11 ms (0.0 s .. 25.09 ms)
```
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):
```
fd --hidden --no-ignore '.*[0-9]\.jpg$' ~
time 892.6 ms (839.0 ms .. 915.4 ms)
0.999 R² (0.997 R² .. 1.000 R²)
mean 871.2 ms (857.9 ms .. 881.3 ms)
std dev 15.50 ms (0.0 s .. 17.49 ms)
```
For this particular example, `fd` is approximately seven times faster than `find -iregex`
and about three times faster than `find -iname`. By the way, both tools found the exact
same 14030 files :smile:.
Finally, let's run `fd` without `--hidden` and `--no-ignore` (this can lead to different
search results, of course):
```
fd '[0-9]\.jpg$' ~
time 159.5 ms (155.8 ms .. 165.3 ms)
0.999 R² (0.996 R² .. 1.000 R²)
mean 158.7 ms (156.5 ms .. 161.6 ms)
std dev 3.263 ms (2.401 ms .. 4.298 ms)
2017-05-13 08:46:22 +00:00
```
2017-06-09 13:04:40 +00:00
2017-09-09 16:29:11 +00: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
be different for you! I encourage everyone to try it out on their own.
2017-05-13 08:46:22 +00:00
2017-09-09 16:29:11 +00: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 15:07:19 +00:00
2017-05-14 18:07:59 +00:00
## Install
2017-06-15 10:25:16 +00:00
With Rust's package manager [cargo](https://github.com/rust-lang/cargo), you can clone, build and install *fd* with a single command:
2017-05-14 18:07:59 +00:00
```
cargo install --git https://github.com/sharkdp/fd
```
2017-06-06 18:47:11 +00:00
Note that rust version *1.16.0* or later is required.
2017-05-14 18:07:59 +00:00
The release page of this repository also includes precompiled binaries for Linux.
2017-05-13 08:46:22 +00:00
2017-06-15 10:25:16 +00:00
On **OS X**, you can use [homebrew](https://brew.sh/):
```
brew install fd
```
2017-08-01 16:43:45 +00:00
On **Arch Linux**, you can install the AUR package [fd-rs-git](https://aur.archlinux.org/packages/fd-rs-git/) via yaourt, or manually:
```
git clone https://aur.archlinux.org/fd-rs-git.git
cd fd-rs-git
makepkg -si
```
2017-05-14 18:07:59 +00:00
## Development
2017-05-09 21:29:14 +00:00
```bash
2017-05-12 12:16:34 +00:00
cargo build --release
2017-05-09 21:29:14 +00:00
```