fd/README.md

294 lines
10 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-09-27 19:47:41 +00:00
[![Build status](https://ci.appveyor.com/api/projects/status/21c4p5fwggc5gy3j?svg=true)](https://ci.appveyor.com/project/sharkdp/fd)
2017-09-17 11:17:40 +00:00
[![Version info](https://img.shields.io/crates/v/fd-find.svg)](https://crates.io/crates/fd-find)
2017-05-12 12:16:34 +00:00
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*).
2017-10-08 18:54:54 +00:00
* It's *fast* (see [benchmarks](#benchmark) 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-10-14 16:04:11 +00:00
* Parallel command execution with a syntax similar to GNU Parallel.
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-09-09 18:39:41 +00:00
![Demo](http://i.imgur.com/kTMFSVU.gif)
2017-05-09 21:35:34 +00:00
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-10-14 20:42:47 +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:
2017-10-14 20:42:47 +00:00
```
2017-09-09 16:29:11 +00:00
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):
2017-10-14 20:42:47 +00:00
```
2017-09-09 16:29:11 +00:00
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):
2017-10-14 20:42:47 +00:00
```
2017-09-09 16:29:11 +00:00
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-10-08 18:54:54 +00: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-14 16:04:11 +00:00
## Parallel Command Execution
If the `--exec` flag is specified alongside a command template, a job pool will be created for
generating and executing commands in parallel with each discovered path as the inputs. The syntax
for generating commands is similar to that of GNU Parallel:
- **{}**: A placeholder token that will be replaced with the discovered path.
- **{.}**: Removes the extension from the path.
- **{/}**: Uses the basename of the discovered path.
- **{//}**: Uses the parent of the discovered path.
- **{/.}**: Uses the basename, with the extension removed.
```sh
# Demonstration of parallel job execution
fd -e flac --exec 'sleep 1; echo $\{SHELL}: {}'
2017-10-14 16:04:11 +00:00
# This also works, because `SHELL` is not a valid token
fd -e flac --exec 'sleep 1; echo ${SHELL}: {}'
# The token is optional -- it gets added at the end by default.
fd -e flac --exec 'echo'
2017-10-14 16:04:11 +00:00
# Real world example of converting flac files into opus files.
fd -e flac --type f --exec 'ffmpeg -i "{}" -c:a libopus "{.}.opus"'
2017-10-14 16:04:11 +00:00
```
2017-05-14 18:07:59 +00:00
## Install
2017-09-09 17:34:51 +00:00
With Rust's package manager [cargo](https://github.com/rust-lang/cargo), you can install *fd* via:
2017-05-14 18:07:59 +00:00
```
2017-09-09 17:34:51 +00:00
cargo install fd-find
2017-05-14 18:07:59 +00:00
```
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-09-10 07:49:53 +00:00
On **macOS**, you can use [Homebrew](http://braumeister.org/formula/fd):
2017-06-15 10:25:16 +00:00
```
brew install fd
```
On **Arch Linux**, you can install the package from the official repos:
```
pacman -S fd-rs
```
On **NixOS**, or any Linux distro you can use [Nix](https://nixos.org/nix/):
```
nix-env -i fd
```
2017-10-08 20:44:54 +00:00
On **Windows**, you can download the pre-built binaries from the [Release page](https://github.com/sharkdp/fd/releases).
2017-10-07 14:18:19 +00:00
2017-05-14 18:07:59 +00:00
## Development
2017-05-09 21:29:14 +00:00
```bash
2017-09-09 16:56:03 +00:00
git clone https://github.com/sharkdp/fd
# Build
cd fd
cargo build
2017-10-07 14:19:47 +00:00
# Run unit tests and integration tests
2017-09-09 16:56:03 +00:00
cargo test
# Install
cargo install
2017-05-09 21:29:14 +00:00
```
2017-09-09 17:32:30 +00: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 18:23:53 +00:00
-s, --case-sensitive Case-sensitive search (default: smart case)
2017-10-22 09:47:05 +00:00
-i, --ignore-case Case-insensitive search (default: smart case)
2017-09-09 17:32:30 +00:00
-a, --absolute-path Show absolute instead of relative paths
2017-10-03 18:23:53 +00: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 17:32:30 +00:00
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
2017-10-03 18:23:53 +00:00
-d, --max-depth <depth> Set maximum search depth (default: none)
-t, --type <filetype> Filter by type: f(ile), d(irectory), (sym)l(ink)
2017-10-03 18:23:53 +00:00
-e, --extension <ext> Filter by file extension
2017-10-22 09:47:05 +00:00
-c, --color <when> When to use colors: never, *auto*, always
-j, --threads <num> Set number of threads to use for searching & executing
-x, --exec <cmd> Execute the given command for each search result
2017-09-09 17:32:30 +00:00
ARGS:
<pattern> the search pattern, a regular expression (optional)
<path> the root directory for the filesystem search (optional)
```
2017-10-06 15:07:26 +00:00
## Tutorial
2017-10-22 17:16:49 +00: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-22 17:16:49 +00:00
### Simple search
2017-10-22 17:16:49 +00: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-22 17:16:49 +00: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-22 17:16:49 +00:00
### Regular expression search
2017-10-22 17:16:49 +00: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-22 17:16:49 +00:00
### Specifying the root directory
2017-10-22 17:16:49 +00:00
If we want so 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
```
2017-10-22 17:16:49 +00:00
### Running *fd* without any arguments
2017-10-22 17:16:49 +00: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-22 17:16:49 +00:00
### Searching for a particular file extension
2017-10-22 17:16:49 +00: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-22 17:16:49 +00: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-22 17:16:49 +00: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-22 17:16:49 +00: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
this behavior, we can use the `-I` (or `--ignore`) option:
``` bash
> fd num_cpu
> fd -I num_cpu
target/debug/deps/libnum_cpus-f5ce7ef99006aa05.rlib
```
2017-10-22 17:16:49 +00:00
To really search *all* files and directories, simply combine the hidden and ignore features to show
everything (`-HI`).
2017-10-22 17:16:49 +00:00
### Using fd with `xargs` or `parallel`
2017-10-22 17:16:49 +00: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-22 17:16:49 +00: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 .