fd/README.md

346 lines
12 KiB
Markdown
Raw Normal View History

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*).
* It's *fast* (see benchmarks 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-05-09 23:29:14 +02:00
2017-05-13 00:05:00 +02:00
## Demo
2017-05-13 00:07:32 +02:00
2017-09-09 20:39:41 +02:00
![Demo](http://i.imgur.com/kTMFSVU.gif)
2017-05-09 23:35:34 +02:00
2017-05-14 20:18:17 +02:00
## Colorized output
2017-06-02 20:34:02 +02: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 20:18:17 +02:00
[here](https://github.com/seebi/dircolors-solarized) or
[here](https://github.com/trapd00r/LS_COLORS).
2017-05-13 10:46:22 +02:00
## Benchmark
2017-09-09 18:29:11 +02: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 15:04:40 +02:00
```
2017-09-09 18:29:11 +02:00
find ~ -iregex '.*[0-9]\.jpg$'
time 6.265 s (6.127 s .. NaN s)
2017-06-09 15:04:40 +02:00
1.000 R² (1.000 R² .. 1.000 R²)
2017-09-09 18:29:11 +02: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 10:46:22 +02:00
2017-09-09 18:29:11 +02:00
time 2.866 s (2.754 s .. 2.964 s)
2017-06-09 15:04:40 +02:00
1.000 R² (0.999 R² .. 1.000 R²)
2017-09-09 18:29:11 +02: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 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
be different for you! I encourage everyone to try it out on their own.
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-05-14 20:07:59 +02:00
## Install
2017-09-09 19:34:51 +02:00
With Rust's package manager [cargo](https://github.com/rust-lang/cargo), you can install *fd* via:
2017-05-14 20:07:59 +02:00
```
2017-09-09 19:34:51 +02:00
cargo install fd-find
2017-05-14 20:07:59 +02:00
```
2017-06-06 20:47:11 +02:00
Note that rust version *1.16.0* or later is required.
2017-05-14 20:07:59 +02:00
The release page of this repository also includes precompiled binaries for Linux.
2017-05-13 10:46:22 +02:00
2017-09-10 09:49:53 +02:00
On **macOS**, you can use [Homebrew](http://braumeister.org/formula/fd):
2017-06-15 12:25:16 +02:00
```
brew install fd
```
2017-09-27 20:53:25 +02:00
On **Arch Linux**, you can install the AUR package [fd-rs](https://aur.archlinux.org/packages/fd-rs/) via yaourt, or manually:
```
2017-09-13 19:30:42 +02:00
git clone https://aur.archlinux.org/fd-rs.git
cd fd-rs
makepkg -si
```
2017-10-07 16:18:19 +02:00
On **Windows**, you can pre-built binaries from the [Release page](https://github.com/sharkdp/fd/releases).
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:
fd [FLAGS/OPTIONS] [<pattern>] [<path>]
FLAGS:
-H, --hidden Search hidden files and directories
-I, --no-ignore Do not respect .(git)ignore files
2017-10-03 20:23:53 +02:00
-s, --case-sensitive Case-sensitive search (default: smart case)
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:
2017-10-03 20:23:53 +02:00
-d, --max-depth <depth> Set maximum search depth (default: none)
2017-10-07 15:15:30 +02:00
-t, --type <filetype> Filter by type: f(ile), d(irectory), s(ymlink)
2017-10-03 20:23:53 +02:00
-e, --extension <ext> Filter by file extension
2017-10-07 15:15:30 +02:00
-c, --color <when> When to use color in the output:
2017-10-03 20:23:53 +02:00
never, auto, always (default: auto)
2017-10-07 15:15:30 +02:00
-j, --threads <num> Set number of threads to use for searching:
2017-10-03 20:23:53 +02:00
(default: number of available CPU cores)
2017-09-09 19:32:30 +02:00
ARGS:
<pattern> the search pattern, a regular expression (optional)
<path> the root directory for the filesystem search (optional)
```
2017-10-06 17:07:26 +02:00
## Tutorial
2017-10-06 17:07:26 +02:00
First, to see all command line options, you can get `fd`'s help text by running:
```
fd --help
```
2017-10-06 17:07:26 +02:00
For the sake of this tutorial, let's assume we have a directory with the following file structure:
```
fd_examples
├── .gitignore
├── desub_dir
│   └── old_test.txt
├── not_file
├── sub_dir
│   ├── .here_be_tests
│   ├── more_dir
│   │   ├── .not_here
│   │   ├── even_further_down
│   │   │   ├── not_me.sh
│   │   │   ├── test_seven
│   │   │   └── testing_eight
│   │   ├── not_file -> /Users/fd_user/Desktop/fd_examples/not_file
│   │   └── test_file_six
│   ├── new_test.txt
│   ├── test_file_five
│   ├── test_file_four
│   └── test_file_three
├── test_file_one
├── test_file_two
├── test_one
└── this_is_a_test
```
2017-10-06 17:07:26 +02:00
If `fd` is called with a single argument (the search pattern), it will perform a recursive search
through the current directory. To search for all files that include the string "test", we can
simply run:
```
2017-10-06 17:07:26 +02:00
> fd test
sub_dir/more_dir/even_further_down/test_seven
sub_dir/more_dir/even_further_down/testing_eight
sub_dir/more_dir/test_file_six
sub_dir/test_file_five
sub_dir/test_file_three
sub_dir/test_four
test_file_one
test_file_two
test_one
this_is_a_test
```
2017-10-06 17:07:26 +02:00
The search pattern is treated as a regular expression. To show only entries that start with "test",
we can simply run:
```
2017-10-06 17:07:26 +02:00
> fd '^test'
sub_dir/more_dir/even_further_down/test_seven
sub_dir/more_dir/even_further_down/testing_eight
sub_dir/more_dir/test_file_six
sub_dir/test_file_five
sub_dir/test_file_three
2017-10-06 17:07:26 +02:00
sub_dir/test_four
test_file_one
test_file_two
test_one
```
2017-10-06 17:07:26 +02:00
Note that `fd` does not show hidden files (`.here_be_tests`) by default. To change this, we can use
the `-H` (or `--hidden`) option:
```
2017-10-06 17:07:26 +02:00
> fd -H test
sub_dir/.here_be_tests
sub_dir/more_dir/even_further_down/test_seven
sub_dir/more_dir/even_further_down/testing_eight
sub_dir/more_dir/test_file_six
sub_dir/test_file_five
2017-10-06 17:07:26 +02:00
sub_dir/test_file_four
sub_dir/test_file_three
test_file_one
test_file_two
test_one
2017-10-06 17:07:26 +02:00
this_is_a_test
```
2017-10-06 17:07:26 +02:00
If we are interested in showing the results from a particular directory, we can specify the root of
the search as a second argument:
```
2017-10-06 17:07:26 +02:00
> fd test sub_dir
sub_dir/more_dir/even_further_down/test_seven
sub_dir/more_dir/even_further_down/testing_eight
sub_dir/more_dir/test_file_six
sub_dir/test_file_five
sub_dir/test_file_three
sub_dir/test_four
```
2017-10-06 17:07:26 +02:00
If we don't give *any* arguments to `fd`, it simply shows all entries in the current directory,
recursively (like `ls -R`):
```
2017-10-06 17:07:26 +02:00
> fd
not_file
sub_dir
sub_dir/more_dir
sub_dir/more_dir/even_further_down
sub_dir/more_dir/even_further_down/test_seven
sub_dir/more_dir/even_further_down/testing_eight
sub_dir/more_dir/not_file
sub_dir/more_dir/test_file_six
sub_dir/test_file_five
sub_dir/test_file_three
sub_dir/test_four
test_file_one
test_file_two
test_one
this_is_a_test
```
2017-10-06 17:07:26 +02:00
If we work in a directory that is a Git repository (or includes several Git repositories), `fd`
does not search folders (and does not show files) that match the `.gitignore` pattern. For example,
imagine we had a `.gitignore` file with the following content:
```
*.sh
```
2017-10-06 17:07:26 +02:00
In this case, `fd` would not show any files that end in `.sh`. To disable this behavior, we can
use the `-I` (or `--ignore`) option:
```
2017-10-06 17:07:26 +02:00
> fd -I me
sub_dir/more_dir/even_further_down/not_me.sh
```
2017-10-06 17:07:26 +02:00
To really search *all* files and directories, we can combine the hidden and ignore features to show
everything (`-HI`):
```
2017-10-06 17:07:26 +02:00
fd -HI 'not|here'
not_file
sub_dir/.here_be_tests
sub_dir/more_dir/.not_here
sub_dir/more_dir/even_further_down/not_me.sh
sub_dir/more_dir/not_file
```
2017-10-06 17:07:26 +02:00
Searching for a file extension is easy too, using the `-e` (or `--file-extensions`) switch for file
extensions:
```
2017-10-06 17:07:26 +02:00
> fd -e sh
sub_dir/more_dir/even_further_down/not_me.sh
```
2017-10-06 17:07:26 +02:00
Next, we can even use a pattern in combination with `-e` to search for a regex pattern over the
files that end in the specified extension.
```
2017-10-06 17:07:26 +02:00
> fd -e txt test
fd_examples/desub_dir/old_test.txt
fd_examples/sub_dir/new_test.txt
```
2017-10-06 17:07:26 +02:00
What if we wanted to run a command for each of the search results? We can use `xargs` to do that:
`fd -0 'test' | xargs -0 -I {} cp {} {}.new`
In this example there are a couple things to take note:
2017-10-06 17:07:26 +02:00
- First we are telling `fd` we want a null character to seperate the files `-0`, this is
important when passing to `xargs`.
- Second, we are piping the output to `xargs` and telling this program to expect input null
terminated with `-0` (the same syntax that `fd` was built with).
- Then for fun we are using `-I` to replace a string `{}` and lauching `cp` to copy the file `{}`
to a file ending in `{}.new`.
2017-10-06 17:07:26 +02:00
`fd` can also show us the absolute path vs. the full path with `-a` (`--absolute-path`):
```
2017-10-06 17:07:26 +02:00
> fd -a new
/Users/fd_user/fd_examples/sub_dir/more_dir/even_further_down/test_seven.new
/Users/fd_user/fd_examples/sub_dir/more_dir/even_further_down/testing_eight.new
/Users/fd_user/fd_examples/sub_dir/more_dir/test_file_six.new
/Users/fd_user/fd_examples/sub_dir/test_file_five.new
/Users/fd_user/fd_examples/sub_dir/test_file_four.new
/Users/fd_user/fd_examples/sub_dir/test_file_three.new
/Users/fd_user/fd_examples/test_file_one.new
/Users/fd_user/fd_examples/test_file_two.new
/Users/fd_user/fd_examples/test_one.new
/Users/fd_user/fd_examples/this_is_a_test.new
```