fd/README.md

318 lines
11 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).
## 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
# 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
2017-10-14 16:04:11 +00:00
```
2017-05-14 18:07:59 +00:00
## Install
2017-11-16 07:19:20 +00:00
### From source
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-10-25 20:43:36 +00:00
Note that rust version *1.19.0* or later is required.
2017-05-13 08:46:22 +00:00
2017-11-16 07:19:20 +00:00
### From binaries
The [release page](https://github.com/sharkdp/fd/releases) includes precompiled binaries for Linux, macOS and Windows.
### On macOS
You can install [this Homebrew package](http://braumeister.org/formula/fd):
2017-06-15 10:25:16 +00:00
```
brew install fd
```
2017-11-16 07:19:20 +00:00
### On Arch Linux
You can install [the fd-rs package](https://www.archlinux.org/packages/community/x86_64/fd-rs/) from the official repos:
```
pacman -S fd-rs
```
2017-11-16 07:19:20 +00:00
### On NixOS / via Nix
You can use the [Nix package manager](https://nixos.org/nix/) to install `fd`:
```
nix-env -i fd
```
2017-11-16 07:19:20 +00:00
### Windows
You can download pre-built binaries from the [release page](https://github.com/sharkdp/fd/releases).
### FreeBSD
2017-10-07 14:18:19 +00:00
2017-11-16 07:19:20 +00:00
You can install `sysutils/fd` via portmaster:
```
portmaster sysutils/fd
```
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-25 20:43:36 +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)
-e, --extension <ext> Filter by file extension
2017-11-15 22:34:32 +00:00
-x, --exec <cmd>... Execute a command for each search result
2017-10-25 20:43:36 +00:00
-E, --exclude <pattern>... Exclude entries that match the given glob pattern.
-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 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 .