https://github.com/sharkdp/fd Skip to content Sign up * Product + Features + Mobile + Actions + Codespaces + Packages + Security + Code review + Issues + Integrations + GitHub Sponsors + Customer stories * Team * Enterprise * Explore + Explore GitHub + Learn and contribute + Topics + Collections + Trending + Learning Lab + Open source guides + Connect with others + The ReadME Project + Events + Community forum + GitHub Education + GitHub Stars program * Marketplace * Pricing + Plans + Compare plans + Contact Sales + Education [ ] * # In this repository All GitHub | Jump to | * No suggested jump to results * # In this repository All GitHub | Jump to | * # In this user All GitHub | Jump to | * # In this repository All GitHub | Jump to | Sign in Sign up {{ message }} sharkdp / fd Public * * Notifications * Fork 592 * Star 22.5k A simple, fast and user-friendly alternative to 'find' License View license 22.5k stars 592 forks Star Notifications * Code * Issues 53 * Pull requests 6 * Actions * Security * Insights More * Code * Issues * Pull requests * Actions * Security * Insights This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. master Switch branches/tags [ ] Branches Tags Could not load branches Nothing to show {{ refName }} default View all branches Could not load tags Nothing to show {{ refName }} default View all tags 5 branches 28 tags Code Latest commit @tavianator tavianator Merge pull request #1019 from rtzoeller/nix_limit_features ... 6782c21 May 18, 2022 Merge pull request #1019 from rtzoeller/nix_limit_features Limit nix features 6782c21 Git stats * 987 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time .github Bump lscolors from 0.8.1 to 0.9.0 Mar 4, 2022 contrib/completion Add a couple of options to zsh completion Jan 6, 2022 doc Update help text and man page May 15, 2022 src Merge remote-tracking branch 'origin/master' into yyogo/master May 15, 2022 tests Merge remote-tracking branch 'origin/master' into yyogo/master May 15, 2022 .gitignore Re-write in rust May 12, 2017 CHANGELOG.md Merge remote-tracking branch 'origin/master' into yyogo/master May 15, 2022 CONTRIBUTING.md Add CHANGELOG section to CONTRIBUTING.md Dec 1, 2020 Cargo.lock Limit nix features May 18, 2022 Cargo.toml Limit nix features May 18, 2022 LICENSE-APACHE Remove outdated license headers (not strictly required by Apache-2.0) Apr 3, 2020 LICENSE-MIT Update LICENSE terms => 2021 Feb 14, 2021 README.md Update README.md Apr 20, 2022 build.rs Bump lscolors from 0.8.1 to 0.9.0 Mar 4, 2022 clippy.toml Bump lscolors from 0.8.1 to 0.9.0 Mar 4, 2022 View code [ ] fd Features Demo How to use Simple search Regular expression search Specifying the root directory List all files, recursively Searching for a particular file extension Searching for a particular file name Hidden and ignored files Matching the full path Command execution Examples Placeholder syntax Parallel vs. serial execution Excluding specific files or directories Deleting files Command-line options Benchmark Troubleshooting Colorized output fd does not find my file! fd doesn't seem to interpret my regex pattern correctly "Command not found" for aliases or shell functions Integration with other programs Using fd with fzf Using fd with rofi Example Using fd with emacs Printing the output as a tree Using fd with xargs or parallel Installation On Ubuntu On Debian On Fedora On Alpine Linux On Arch Linux On Gentoo Linux On openSUSE Linux On Void Linux On RedHat Enterprise Linux 8 (RHEL8) or Almalinux 8 or Rocky Linux 8 On macOS On Windows On GuixOS On NixOS / via Nix On FreeBSD From npm From source From binaries Development Maintainers License README.md fd CICD Version info [Zhong Wen ] [hangugeo] fd is a program to find entries in your filesystem. It is a simple, fast and user-friendly alternative to find. While it does not aim to support all of find's powerful functionality, it provides sensible (opinionated) defaults for a majority of use cases. Quick links: * How to use * Installation * Troubleshooting Features * Intuitive syntax: fd PATTERN instead of find -iname '*PATTERN*'. * Regular expression (default) and glob-based patterns. * Very fast due to parallelized directory traversal. * Uses colors to highlight different file types (same as ls). * Supports parallel command execution * Smart case: the search is case-insensitive by default. It switches to case-sensitive if the pattern contains an uppercase character*. * Ignores hidden directories and files, by default. * Ignores patterns from your .gitignore, by default. * The command name is 50% shorter* than find :-). Demo Demo How to use First, to get an overview of all available command line options, you can either run fd -h for a concise help message or fd --help for a more detailed version. Simple search 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): > fd netfl Software/python/imdb-ratings/netflix-details.py If called with just a single argument like this, fd searches the current directory recursively for any entries that contain the pattern netfl. Regular expression search The search pattern is treated as a regular expression. Here, we search for entries that start with x and end with rc: > cd /etc > fd '^x.*rc$' X11/xinit/xinitrc X11/xinit/xserverrc The regular expression syntax used by fd is documented here. Specifying the root directory If we want to search a specific directory, it can be given as a second argument to fd: > fd passwd /etc /etc/default/passwd /etc/pam.d/passwd /etc/passwd List all files, recursively 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): > cd fd/tests > fd testenv testenv/mod.rs tests.rs If you want to use this functionality to list all files in a given directory, you have to use a catch-all pattern such as . or ^: > fd . fd/tests/ testenv testenv/mod.rs tests.rs Searching for a particular file extension 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: > cd fd > fd -e md CONTRIBUTING.md README.md The -e option can be used in combination with a search pattern: > fd -e rs mod src/fshelper/mod.rs src/lscolors/mod.rs tests/testenv/mod.rs Searching for a particular file name To find files with exactly the provided search pattern, use the -g (or --glob) option: > fd -g libc.so /usr /usr/lib32/libc.so /usr/lib/libc.so 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: > fd pre-commit > fd -H pre-commit .git/hooks/pre-commit.sample 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 --no-ignore) option: > fd num_cpu > fd -I num_cpu target/debug/deps/libnum_cpus-f5ce7ef99006aa05.rlib To really search all files and directories, simply combine the hidden and ignore features to show everything (-HI). Matching the full path By default, fd only matches the filename of each file. However, using the --full-path or -p option, you can match against the full path. > fd -p -g '**/.git/config' > fd -p '.*/lesson-\d+/[a-z]+.(jpg|png)' Command execution Instead of just showing the search results, you often want to do something with them. fd provides two ways to execute external commands for each of your search results: * The -x/--exec option runs an external command for each of the search results (in parallel). * The -X/--exec-batch option launches the external command once, with all search results as arguments. Examples Recursively find all zip archives and unpack them: fd -e zip -x unzip If there are two such files, file1.zip and backup/file2.zip, this would execute unzip file1.zip and unzip backup/file2.zip. The two unzip processes run in parallel (if the files are found fast enough). Find all *.h and *.cpp files and auto-format them inplace with clang-format -i: fd -e h -e cpp -x clang-format -i Note how the -i option to clang-format can be passed as a separate argument. This is why we put the -x option last. Find all test_*.py files and open them in your favorite editor: fd -g 'test_*.py' -X vim Note that we use capital -X here to open a single vim instance. If there are two such files, test_basic.py and lib/test_advanced.py, this will run vim test_basic.py lib/test_advanced.py. To see details like file permissions, owners, file sizes etc., you can tell fd to show them by running ls for each result: fd ... -X ls -lhd --color=always This pattern is so useful that fd provides a shortcut. You can use the -l/--list-details option to execute ls in this way: fd ... -l. The -X option is also useful when combining fd with ripgrep (rg) in order to search within a certain class of files, like all C++ source files: fd -e cpp -e cxx -e h -e hpp -X rg 'std::cout' Convert all *.jpg files to *.png files: fd -e jpg -x convert {} {.}.png Here, {} is a placeholder for the search result. {.} is the same, without the file extension. See below for more details on the placeholder syntax. Placeholder syntax The -x and -X options take a command template as a series of arguments (instead of a single string). If you want to add additional options to fd after the command template, you can terminate it with a \;. 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). * {//}: The parent of the discovered path (documents/images). * {/.}: The basename, with the extension removed (party). If you do not include a placeholder, fd automatically adds a {} at the end. Parallel vs. serial execution For -x/--exec, you can control the number of parallel jobs by using the -j/--threads option. Use --threads=1 for serial execution. 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: > fd -H -E .git ... We can also use this to skip mounted directories: > fd -E /mnt/external-drive ... .. or to skip certain file types: > 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: > cat ~/.fdignore /mnt/external-drive *.bak Note: fd also supports .ignore files that are used by other programs such as rg or ag. If you want fd to ignore these patterns globally, you can put them in fd's global ignore file. This is usually located in ~/.config/fd/ ignore in macOS or Linux, and %APPDATA%\fd\ignore in Windows. Deleting files You can use fd to remove all files and directories that are matched by your search pattern. If you only want to remove files, you can use the --exec-batch/-X option to call rm. For example, to recursively remove all .DS_Store files, run: > fd -H '^\.DS_Store$' -tf -X rm If you are unsure, always call fd without -X rm first. Alternatively, use rms "interactive" option: > fd -H '^\.DS_Store$' -tf -X rm -i If you also want to remove a certain class of directories, you can use the same technique. You will have to use rms --recursive/-r flag to remove directories. Note: there are scenarios where using fd ... -X rm -r can cause race conditions: if you have a path like .../foo/bar/foo/... and want to remove all directories named foo, you can end up in a situation where the outer foo directory is removed first, leading to (harmless) "'foo /bar/foo': No such file or directory" errors in the rm call. Command-line options This is the output of fd -h. To see the full set of command-line options, use fd --help which also includes a much more detailed help text. USAGE: fd [FLAGS/OPTIONS] [] [...] FLAGS: -H, --hidden Search hidden files and directories -I, --no-ignore Do not respect .(git|fd)ignore files -s, --case-sensitive Case-sensitive search (default: smart case) -i, --ignore-case Case-insensitive search (default: smart case) -g, --glob Glob-based search (default: regular expression) -a, --absolute-path Show absolute instead of relative paths -l, --list-details Use a long listing format with file metadata -L, --follow Follow symbolic links -p, --full-path Search full abs. path (default: filename only) -h, --help Prints help information -V, --version Prints version information OPTIONS: -d, --max-depth Set maximum search depth (default: none) -t, --type ... Filter by type: file (f), directory (d), symlink (l), executable (x), empty (e), socket (s), pipe (p) -e, --extension ... Filter by file extension -x, --exec Execute a command for each search result -X, --exec-batch Execute a command with all search results at once -E, --exclude ... Exclude entries that match the given glob pattern -c, --color When to use colors: never, *auto*, always -S, --size ... Limit results based on the size of files --changed-within Filter by file modification time (newer than) --changed-before Filter by file modification time (older than) -o, --owner Filter by owning user and/or group ARGS: the search pattern (a regular expression, unless '--glob' is used; optional) ... the root directory for the filesystem search (optional) Benchmark Let's search my home folder for files that end in [0-9].jpg. It contains ~190.000 subdirectories and about a million files. For averaging and statistical analysis, I'm using hyperfine. The following benchmarks are performed with a "warm"/pre-filled disk-cache (results for a "cold" disk-cache show the same trends). Let's start with find: Benchmark #1: find ~ -iregex '.*[0-9]\.jpg$' Time (mean +- s): 7.236 s +- 0.090 s Range (min ... max): 7.133 s ... 7.385 s find is much faster if it does not need to perform a regular-expression search: Benchmark #2: find ~ -iname '*[0-9].jpg' Time (mean +- s): 3.914 s +- 0.027 s Range (min ... max): 3.876 s ... 3.964 s 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): Benchmark #3: fd -HI '.*[0-9]\.jpg$' ~ Time (mean +- s): 811.6 ms +- 26.9 ms Range (min ... max): 786.0 ms ... 870.7 ms 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 . Finally, let's run fd without --hidden and --no-ignore (this can lead to different 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: Benchmark #4: fd '[0-9]\.jpg$' ~ Time (mean +- s): 123.7 ms +- 6.0 ms Range (min ... max): 118.8 ms ... 140.0 ms 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. See this repository for all necessary scripts. Concerning fd's speed, the main credit goes to the regex and ignore crates that are also used in ripgrep (check it out!). Troubleshooting Colorized output fd can colorize files by extension, just like ls. In order for this to work, the environment variable LS_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 on Windows or if you are looking for alternative, more complete (or more colorful) variants, see here, here or here. fd also honors the NO_COLOR environment variable. fd does not find my file! Remember that fd ignores hidden directories and files by default. It also ignores patterns from .gitignore files. If you want to make sure to find absolutely every possible file, always use the options -H and -I to disable these two features: > fd -HI ... fd doesn't seem to interpret my regex pattern correctly A lot of special regex characters (like [], ^, $, ..) are also special characters in your shell. If in doubt, always make sure to put single quotes around the regex pattern: > fd '^[A-Z][0-9]+$' If your pattern starts with a dash, you have to add -- to signal the end of command line options. Otherwise, the pattern will be interpreted as a command-line option. Alternatively, use a character class with a single hyphen character: > fd -- '-pattern' > fd '[-]pattern' "Command not found" for aliases or shell functions Shell aliases and shell functions can not be used for command execution via fd -x or fd -X. In zsh, you can make the alias global via alias -g myalias="...". In bash, you can use export -f my_function to make available to child processes. You would still need to call fd -x bash -c 'my_function "$1"' bash. For other use cases or shells, use a (temporary) shell script. Integration with other programs Using fd with fzf You can use fd to generate input for the command-line fuzzy finder fzf: export FZF_DEFAULT_COMMAND='fd --type file' export FZF_CTRL_T_COMMAND="$FZF_DEFAULT_COMMAND" Then, you can type vim 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): export FZF_DEFAULT_COMMAND='fd --type file --follow --hidden --exclude .git' You can even use fd's colored output inside fzf by setting: export FZF_DEFAULT_COMMAND="fd --type file --color=always" export FZF_DEFAULT_OPTS="--ansi" For more details, see the Tips section of the fzf README. Using fd with rofi rofi is a graphical launch menu application that is able to create menus by reading from stdin. Piping fd output into rofis -dmenu mode creates fuzzy-searchable lists of files and directories. Example Create a case-insensitive searchable multi-select list of PDF files under your $HOME directory and open the selection with your configured PDF viewer. To list all file types, drop the -e pdf argument. fd --type f -e pdf . $HOME | rofi -keep-right -dmenu -i -p FILES -multi-select | xargs -I {} xdg-open {} To modify the list that is presented by rofi, add arguments to the fd command. To modify the search behaviour of rofi, add arguments to the rofi command. Using fd with emacs The emacs package find-file-in-project can use fd to find files. After installing find-file-in-project, add the line (setq ffip-use-rust-fd t) to your ~/.emacs or ~/.emacs.d/init.el file. In emacs, run M-x find-file-in-project-by-selected to find matching files. Alternatively, run M-x find-file-in-project to list all available files in the project. Printing the output as a tree To format the output of fd similar to the tree command, install as-tree and pipe the output of fd to as-tree: fd | as-tree This can be more useful than running tree by itself because tree does not ignore any files by default, nor does it support as rich a set of options as fd does to control what to print: fd --extension rs | as-tree . +-- build.rs +-- src +-- app.rs +-- error.rs For more information about as-tree, see the as-tree README. Using fd with xargs or parallel Note that fd has a builtin feature for command execution with its -x/ --exec and -X/--exec-batch options. If you prefer, you can still use it in combination with xargs: > fd -0 -e rs | xargs -0 wc -l 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. Installation Packaging status On Ubuntu ... and other Debian-based Linux distributions. If you run Ubuntu 19.04 (Disco Dingo) or newer, you can install the officially maintained package: sudo apt install fd-find Note that the binary is called fdfind as the binary name fd is already used by another package. It is recommended that after installation, you add a link to fd by executing command ln -s $(which fdfind) ~/.local/bin/fd, in order to use fd in the same way as in this documentation. Make sure that $HOME/.local/bin is in your $PATH. If you use an older version of Ubuntu, you can download the latest .deb package from the release page and install it via: sudo dpkg -i fd_8.3.2_amd64.deb # adapt version number and architecture On Debian If you run Debian Buster or newer, you can install the officially maintained Debian package: sudo apt-get install fd-find Note that the binary is called fdfind as the binary name fd is already used by another package. It is recommended that after installation, you add a link to fd by executing command ln -s $(which fdfind) ~/.local/bin/fd, in order to use fd in the same way as in this documentation. Make sure that $HOME/.local/bin is in your $PATH. On Fedora Starting with Fedora 28, you can install fd from the official package sources: dnf install fd-find On Alpine Linux You can install the fd package from the official sources, provided you have the appropriate repository enabled: apk add fd On Arch Linux You can install the fd package from the official repos: pacman -S fd On Gentoo Linux You can use the fd ebuild from the official repo: emerge -av fd On openSUSE Linux You can install the fd package from the official repo: zypper in fd On Void Linux You can install fd via xbps-install: xbps-install -S fd On RedHat Enterprise Linux 8 (RHEL8) or Almalinux 8 or Rocky Linux 8 Get the latest fd-v*-x86_64-unknown-linux-gnu.tar.gz file from sharkdp on github tar xf fd-v*-x86_64-unknown-linux-gnu.tar.gz chown -R root:root fd-v*-x86_64-unknown-linux-gnu cd fd-v*-x86_64-unknown-linux-gnu sudo cp fd /bin gzip fd.1 chown root:root fd.1.gz sudo cp fd.1.gz /usr/share/man/man1 sudo cp autocomplete/fd.bash /usr/share/bash-completion/completions/fd source /usr/share/bash-completion/completions/fd fd On macOS You can install fd with Homebrew: brew install fd ... or with MacPorts: sudo port install fd On Windows You can download pre-built binaries from the release page. Alternatively, you can install fd via Scoop: scoop install fd Or via Chocolatey: choco install fd On GuixOS You can install the fd package from the official repo: guix install fd On NixOS / via Nix You can use the Nix package manager to install fd: nix-env -i fd On FreeBSD You can install the fd-find package from the official repo: pkg install fd-find From npm On linux and macOS, you can install the fd-find package: npm install -g fd-find From source With Rust's package manager cargo, you can install fd via: cargo install fd-find Note that rust version 1.56.0 or later is required. make is also needed for the build. From binaries The release page includes precompiled binaries for Linux, macOS and Windows. Statically-linked binaries are also available: look for archives with musl in the file name. Development git clone https://github.com/sharkdp/fd # Build cd fd cargo build # Run unit tests and integration tests cargo test # Install cargo install --path . Maintainers * sharkdp * tmccombs * tavianator License Copyright (c) 2017-2021 The fd developers fd is distributed under the terms of both the MIT License and the Apache License 2.0. See the LICENSE-APACHE and LICENSE-MIT files for license details. About A simple, fast and user-friendly alternative to 'find' Topics search rust cli terminal command-line tool filesystem regex hacktoberfest Resources Readme License View license Stars 22.5k stars Watchers 146 watching Forks 592 forks Releases 28 v8.3.2 Latest Jan 29, 2022 + 27 releases Sponsor this project * * Learn more about GitHub Sponsors Contributors 137 * @sharkdp * @tmccombs * @dependabot[bot] * @tavianator * @reima * @alexmaco * @jcaplan * @marionebl * @iology * @mmstick * @FallenWarrior2k + 126 contributors Languages * Rust 95.0% * Shell 5.0% * (c) 2022 GitHub, Inc. * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.