Use UNIX_EPOCH.checked_add(...) so an out-of-range value returns None
and propagates through the existing ? like every other parse failure in
TimeFilter::from_str, rather than panicking via SystemTime's Add. See #2081.
Demonstrates that a '@'-timestamp large enough to overflow SystemTime
panics ('overflow when adding duration to instant') instead of being
rejected like other unparseable time inputs. See #2081.
The checksum example under 'Command execution' was missing the
'bash' language tag on its opening fence, unlike every other shell
example in the file, so it didn't get syntax highlighting.
use `ignore::Error::io_error()` to inspect the `std::io::Error` insted
of pattern matching on `ignore::Error::Io`.
This avoids relying on the implementation of ignore and how it organizes
the error. In particular, this would allow us to handle if the IO error
was wrapped in a `WithDepth`, as would be the case if
BurntSushi/ripgrep#3458 was merged.
This also allows us to remove some duplicate code.
The path-separator diagnostic (#1873, made unconditional for the primary
pattern in #1975) only inspected opts.pattern. --and patterns (opts.exprs)
are chained with the primary pattern and matched against the file name in
exactly the same way, so a path separator in any of them is the same silent
"no results" footgun. Factor the per-pattern check into a helper and apply
it to the primary pattern plus every --and pattern, mirroring how
ensure_use_hidden_option_for_leading_dot_pattern already iterates all
patterns. --full-path still suppresses the diagnostic. Adds a regression test.
See #1873.
Updated help string to clarify that fd respects gitignore by default.
Also added verbage to clarify that globbing and regex patterns are
accepted without a flag.
Short help stays minimal; long help and man page explain that extension
filtering applies to directories as well unless --type restricts results.
Addresses maintainer feedback on #1922. Fixes#1693
Co-authored-by: Cursor <cursoragent@cursor.com>
Signed-off-by: SAY-5 <SAY-5@users.noreply.github.com>
On Windows the regex-over-full-path match uses `\`, so the
pattern `one/two/c` cannot match a real entry. The diagnostic-
didn't-fire behaviour this test pins is already covered by the
fact that the invocation does not error. Gate it to non-Windows
per tmccombs's CI feedback on the PR.
Without --full-path, fd matches patterns against file names, so any pattern
containing a path separator can never match. The previous implementation
in main.rs fired the path-separator diagnostic only when the pattern also
named an existing directory on disk, so the most common Linux/macOS typo
- pasting a full path as the pattern - silently returned zero matches.
Restructure ensure_search_pattern_is_not_a_path so that any '/' in the
pattern triggers the diagnostic unconditionally, and keep the existing
'directory must exist on disk' guard only for the native '\' separator
on Windows, which is also the regex escape character. The Windows check
is short-circuited via '||' so the is_dir syscall never runs when the
pattern already contains '/'. The #[cfg_attr(not(windows), allow(unused_mut))]
attribute keeps the mut binding warning-free on non-Windows targets.
Update the error message to drop the now-ambiguous parenthetical that
showed the platform-specific separator character, and widen the
integration test assertions to cover the full first line so the
assert_failure_with_error helper (which trims lines on both sides) cannot
early-accept on a partial prefix.
Closes#1873
Signed-off-by: SAY-5 <SAY-5@users.noreply.github.com>
Add expectations for making pull requests to CONTRIBUTING.md
My main objective is to try to discourage low-effort AI generated pull
requests. But I realized several of the guidelines were actually more
general, so made the section as a whole more general.
Add the --ignore-parent flag, mirroring the existing pattern where
--ignore-vcs overrides --no-ignore-vcs. This lets users undo
--no-ignore-parent in aliases or config files.
Closes#1958
Update the versions of Windows and Mac OSes used in build matrix.
Also add back intel Mac since on the latest version that is still
supported until 2027.
Fixes: #1945Fixes: #1918
The summary line `-E, --exclude <pattern>` is misleading because fd
defaults to regex for its main search pattern, but --exclude takes a
glob. Rename the value placeholder to "glob" in the CLI help, man page,
and README to match the actual behavior.
Fixes#1724
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Instead of calling current_dir() for every entry when --full-path is
set, cache it once in Config at startup. This eliminates the need for
FatalError handling and makes path resolution infallible during the
walk. If the cwd can't be retrieved, fd now fails early with a clear
error message.
- Add FatalError variant to WorkerResult for unrecoverable errors
- Extract search_str_for_entry() helper to propagate IO errors from path_absolute_form
- Propagate fatal errors through job and batch execution paths
- Add regression test for invalid cwd scenario
- Update CHANGELOG for #1900
Instead of calling `is_dir` on the path, call it on the file_type of the
DirEntry, since we should already have that information without needing
to do another syscall.
Fixes: #1913
Add documentation for generating completions using fd --gen-completions,
while keeping and clarifying the existing instructions for pre-built
completions from release archives.
- Clarify that pre-built completions are in release archives (autocomplete dir)
- Add new section for generating completions with fd --gen-completions
- Include examples for bash, zsh, fish, and powershell
Fixes#1843
Changed the host() function for Windows to return '/' instead of ''
to generate RFC 3986 compliant file URLs with three slashes.
Before: file://C:/test/hi%20there.txt (broken)
After: file:///C:/test/hi%20there.txt (works)
This fixes hyperlinks failing on Windows when file paths contain
spaces or other characters that require percent-encoding.
This update fixes fish shell completion formatting issues where
ValueEnum descriptions were not properly separated with tabs,
causing fish to fail parsing the completions.
The fix was introduced in clap-rs/clap#5874 which changed the
fish completion generator to use proper multi-line format with
quotes instead of the brace format.
Fixes fish shell completions for options like --type and --color
that have enum values with descriptions.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit changes the way that the binary executable of fd is located
during integration tests. Previously, the find_fd_exe function would just
navigate in the parent directory and try to find the binary here. This
method is not appropriate as it assumes that the test directory will have
the same layout as the build directory, which also leaks the build time
configuration.
With this patch, the location of the binary executable is read using the
CARGO_BIN_EXE_fd environment variable. The code at first tries to read
the variable at run time, and if it is not available it then uses the env!
macro which returns the value of the variable exposed at compile time.
This way of reading the binary location makes the code more flexible and
friendlier to cross compile.
This commit closes#1838 .
Signed-off-by: Andreas Stergiopoulos <andreas.stergiopoulos@smile.fr>
If you use --print0 with --exec, it will now print a \0 between each set
of commands run. That is, between the output for the commands run for
each found item.
Fixes: #1797
Upstream writes: “The project is also published as jemallocator for
historical reasons. The two crates are the same except names. For new
projects, it's recommended to use tikv-xxx versions instead.”
By using an older version of rust to build the artifacts on windows.
Alternatively we could build separate artifacts for windows 7, and
continue using the latest version of rust for later versions of windows
that are more optimized for more recent versions.
Fixes: #1550
The problem, is I based the code on the implementation in ripgrep. But
while ripgrep is writing directly to the stream, I am using a Formatter,
which means I have to write characters, not raw bytes.
Thus we need to percent encode all non-ascii bytes (or we could switch
to writing bytes directly, but that would be more complicated, and I
think percent encoding is safer anyway).
cross doesn't pass all environment variables through into the build
container, so JEMALLOC_SYS_WITH_LG_PAGE=16 wasn't being picked up from
the host. Instead, set it explicitly in Cross.toml.
Link: https://github.com/cross-rs/cross/wiki/Configuration
Prior to this version, `Command` didn't properly escape command line
arguments on windows.
Although, the risk of attacker controlled arguments passed through fd is
relatively small, I think it is best to upgrade to a version that fixes
this.
The biggest risk for users is probably running fd with `--exec` or
`--exec-batch` on directories that contain files with names controlled
by another party (for example a git repo that you cloned).
See: https://blog.rust-lang.org/2024/04/09/cve-2024-24576.html
Security: CVE-2024-24576
The previous behaviour was designed to mimic the output buffering of
typical UNIX tools: line-buffered if stdout is a TTY, and fully-buffered
otherwise. More precicely, when printing to a terminal, fd would flush
explicitly after printing any buffered results, then flush after every
single result once streaming mode started. When not printing to a
terminal, fd never explicitly flushed, so writes would only happen as
the BufWriter filled up.
The new behaviour actually unifies the TTY and non-TTY cases: we flush
after printing the buffered results, then once we start streaming, we
flush after each batch, but *only when the channel is empty*. This
provides a good balance: if the channel is empty, the receiver thread
might as well flush before it goes to sleep waiting for more results.
If the channel is non-empty, we might as well process those results
before deciding to flush.
For TTYs, this should improve performance by consolidating write() calls
without sacrificing interactivity. For non-TTYs, we'll be flushing more
often, but only when the receiver would otherwise have nothing to do,
thus improving interactivity without sacrificing performance. This is
particularly handy when fd is piped into another command (such as head
or grep): with the old behaviour, fd could wait for the whole traversal
to finish before printing anything. With the new behaviour, fd will
print those results soon after they are received.
Fixes#1313.
Set a limit of how many threads fd will use by default. On hosts that
have a large number of cores, using additional threads has diminishing
returns, and having large numbers of threads increases the setup cost.
Thus we don't necessarily want to use the same number of threads as we
have cores.
Fixes: #1203
I think this might help startup time a little bit, since it looks like
on linux at least the std implementation uses syscalls to determine the
parallelism, whereas num_cpus was processing the /proc/cpuinfo file.
It also removes another dependency.
The users crate is no longer maintained. There is a maintained fork
called uzers, but we already have a dependency on nix, and that has the
functionality we need.
This also fixes a couple of problems that are now errors:
- Remove use of unstable-grouped feature flag that no longer exists
- Fix some conflicts rules with non-existant options
* has_results should have been quiet
* count doesn't exist. I'm not sure where it came from
Fixes: #1397
cargo update proc-macro2
Otherwise the error "error[E0635]: unknown feature
`proc_macro_span_shrink`" will display and the build will fail.
Seems to be okay as of nightly 62ebe3a2b 2023-09-08
To update transient dependencies.
Notably, this removes fs_extras, the current version of which has code
that rustc identifies as not being future compatible.
Summary: Currently, `--ignore-vcs` only serves to unset `--no-ignore-vcs`.
There is currently no way to tell fd to respect gitignore files when not in a
git repository. This commit adds the flag `--no-require-git` to make fd always
respect all gitignore files.
This behaves the same as the `--no-require-git` option in [ripgrep](https://github.com/BurntSushi/ripgrep/blob/3bb71b0cb8727ac43237af78ba5c707298de0128/crates/core/app.rs#L2214-L2226)
This commit also contains an unrelated wording fix to CONTRIBUTING.md
Test Plan: `tests/tests.rs`
Background: I am using [Sapling](https://sapling-scm.com/docs/introduction/)
for working with git repositories (including this commit ☺️). Since Sapling
uses `.sl` instead of `.git`, tools using the `ignore` crate (rg and fd) would show gitignored files.
I made a patch (https://github.com/vegerot/ripgrep/commit/ebf17eef22a04450ca86e9dc790db7cb00e11e52)
to `ignore` to respect gitignores with _either_ `.git` or `.sl`. However,
@BurntSushi said he did not want to merge that patch and instead suggested I
use `--no-require-git` (https://github.com/BurntSushi/ripgrep/issues/2374).
This works fine, but I couldn't use this workaround for my other favorite tool!
That's what this patch is for 😁
(a follow-up patch will add a similar `FD_CONFIG_PATH` environment variable
like `RG_CONFIG_PATH`)
Because chrono was depending on an older version of time, and we don't
actually need it with recent versions of chrono.
Relates-To: #1188
Alernative-To: #1190
If passed a full path to the executable (like done in the Makefile) that
value is used in the generated completions. At least for fish this just
doesn't work.
This fixes#1172
Unfortunately, clap_derive can't combine a value_parser of Option<T>
with an optional argument to get a merged Option<T> so we need to do the
check for the nop outside of the value parser.
Also adds some tests for --owner
Fixes: #1163
In particular, we specifically use `long_help` instead of doc comments
because using doc comments will always trim the "." off the end of the
first paragraph, and will include the short help as the first paragraph
of the full help.
Three command line options were added in late 2021
that never made their way into the manpage:
* f8ae334 introduced --no-ignore-parent;
* bf9e6fd introduced --strip-prefix
(later renamed strip-cwd-prefix); and
* 17dd2a6 introduced --batch-size.
This commit updates the manpage content to reflect
the auto-generated output of `fd --help`.
jemalloc will require special flags on devices where page size is not 4K. With default options fd will not work on a Mac Mini M1 where hardware only allow 16K paging size. This commit will allow the user to turn off jemalloc (using --no-default-features) under special circumstances where jemalloc is not usable.
Make sure that using `--no-ignore-vcs` or `--no-ignore` don't also
enable `--no-ignore-parent`. So that if `--no-ignore-vcs` is enabled, it
continues to respect .fdignore and .ignore in the parent directories.
Fixes: #907Fixes: #901
quit_flag is now used to quit the sender threads for any reason, either
due to an interrupt or because the receiver is done.
interrupt_flag is used specifically for ^C interrupts, and causes the
receiver to stop between printing paths, to avoid unfinished escape
sequences when colors are being used.
Fixes#867.
The new ReceiverBuffer struct allows us to factor out the receiver
implementation into a number of helper methods. The new implementation
uses rx.{recv,recv_timeout} instead of a for loop, which enables us to
switch to streaming mode at the right time without waiting for more
results.
Fixes#868.
It can be expensive to color each path component separately, requiring a
stat() call on each component. For deep hierarchies this can result in
quadratic overhead. Instead, just color the path up to the basename as
a directory.
Fixes#720.
Now, the top method is `main`, then comes `run`, then the methods used
in `run` follow. Generally, a method is always declared somewhere after
its first use. This way, you can read the file from top to bottom with
a decreasing level of abstraction (you start with very high-level
processes like setting the current dir and logic for which ls command to
use only comes furher down).
This was caught by Code Quality github action with the message:
> this expression borrows a reference (`&walk::DirEntry`) that is immediately dereferenced by the compiler
Those are:
- `--no-hidden`, which overrides `--hidden`
- `--ignore`, which overrides `--no-ignore`
- `--ignore-vcs`, which overrides `--no-ignore-vcs`
- `--no-follow`, which overrides `--follow`
- `--relative-path`, which overrides `--absolute-path`
This patch uses Chrono for explicit date or datetime parsing, only using
humantime for its relative time parsing. The following formats are accepted:
1. Full RFC3339 parsing, requiring an explicit timezone
2. `YY-MM-DD`, defaulting to time `00:00:00` for the given date in the
local time zone
3. `YY-MM-DD HH:MM:SS` in the local time zone
Fixes#631, #794
* Document the newer and older aliases in the help text
* Documentation for new older aliases, remove commas
* Adds better clarification on alias usage for newer and older
* Fixes inconsistencies in help text for newer and older aliases
MSYS and MSYS2 environments (such as Git Bash) have a UNIX like
filesystem which uses '/' as the path separator rather than '\', but
Rust doesn't know about this by default.
On Windows, check the MSYSTEM environment variable and set the default
value of the --path-separator option to '/' for convenience.
There is no similar detection of Cygwin because there seems to be no way
for Rust (and any native Win32) programs to detect that they're being
called from a Cygwin environment. Cygwin users can use a shell
alias/function/script to wrap fd.
Fixes: https://github.com/sharkdp/fd/issues/537
As export command will not work with fd because fd is just an alias to
fdfind, create a soft link instead of alias.
Addresses https://github.com/sharkdp/fd/issues/728
When --path-separator is used, pass it on to commands run with
--exec(-batch) and --list-details.
On Windows, paths with drive letters (C:\foo) and UNC paths
(\\server\share\path) are handled as expected, though they're unlikely
to be found in normal usage of fd.
Fixes: https://github.com/sharkdp/fd/issues/697
Replace the auto-generated Zsh completion with a full completion script.
This script improves completion support for options and arguments,
which is hard to obtain from an auto-generated completion.
- Full completion support for external commands and options when using
`--exec`/`--exec-batch`.
- The completion for `--type` and `--color` adds descriptions instead of
just values.
- Complete files when using `--ignore-file`.
- Stop completing files for the pattern argument.
- Improve completion for path arguments. Only directories are
completed.
- Single-use options are not offered again.
- Updated exclusions lists for mutual-exclusive options.
- Add support for hidden options (as defined in `app.rs`). They are not
offered for completion, but if present are considered (and their value
may be completed).
Full support for exclusion lists depends of options groups, which was
added in Zsh 5.4. Older Zsh versions, as commented in the completion
script, will just offer most options.
The format of the completion script was taken from ripgrep completion
script. Command completion for `--exec`/`--exec-batch` was taken from
Zsh's `_find` completion.
Currently, https://packages.ubuntu.com/disco/fd-find shows an error.
This is because of the package page that unsupported version was removed.
So I removed the version from the link. That link shows a search result of `fd-find`
and can find OSs that can install `fd-find`.
With an empty pattern, --glob results in no matches. This does not
align with the behavior of --fixed-strings or --regex. Update the
initialization code to handle globs with empty patterns.
Add a new `-l`/`--list` option to show more details about the search results. This is basically
an alias for `--exec-batch ls -l` with some additional `ls` options.
This can be used in order to:
* see metadata like permissions, owner, file size, modification times (#491)
* see symlink targets (#482)
* achieve a deterministic output order (#324, #196, #159)
* avoid duplicate search results when multiple search paths are given (#405)
This new option can be used instead of piping to `head -n <count>` for
improved performance:
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|:---|---:|---:|---:|---:|
| `fd --max-buffer-time=0 flow.yaml` | 153.9 ± 2.5 | 151.3 | 170.3 | 4.21 ± 5.86 |
| `fd --max-buffer-time=0 flow.yaml \| head -n 1` | 145.3 ± 17.4 | 111.0 | 180.2 | 3.98 ± 5.55 |
| `fd --max-results=1 flow.yaml` | 36.5 ± 50.8 | 7.2 | 145.7 | 1.00 |
Note: there is a large standard deviation on the last result due to the
non-deterministic file system traversal. With `--max-results`, we don't
have to traverse the whole filesystem tree, so it's all about luck.
closes#472closes#476
If `/dev/null` doesn't exist or is not on a different partition during
the test for `--one-file-system`, the test is skipped instead of
mistakenly failing.
Instead of having the option do nothing at runtime on unsupported
platforms, it is now only available on the systems that support it in
the first place.
This adds a `--same-file-system` CLI option that instructs the walker to
not cross file system boundaries.
Due to the fact that the corresponding option of the `ignore` crate's
`WalkBuilder` does not support platforms other than Unix and Windows,
the option does nothing on platforms other than those.
Resolves#507
Installing fd does not require using portmaster (it will also build
fd from source). IMHO this is pretty misleading. Let's update the
FreeBSD install instructions to recommend using the binary package
in the official repository like on other systems.
This is just a split commit, refraining from renaming too much.
The drop(tx) call is no longer necessary, as the first sender
is dropped at the end of spawn_senders(..)
Use my new [lscolors](https://github.com/sharkdp/lscolors) crate instead
of the internal `lscolors` module
- Speeds up `LS_COLORS` querying, leading to a nice 25% performance
improvement when
- Adds support for 24-bit colors and background colors
closes#368closes#363
* Multiple `--search-path` arguments can be supplied which replace the positional `path` argument for providing directories which will be searched.
* When a `--search-path` argument is provided, positional `path` arguments will not be allowed
This PR splits `internals.rs` into the `internal` module with multiple
files, and moves `FdOptions` into `opts.rs`.
The main motivation behind this is to move logic for constructing
`FdOptions` out of the main function and more readable and easier to
understand in the `opts` module. The goal will eventually to be able
to write `FdOptions::from(matches)` and have the options constructed.
This patch makes minor changes to make the code a little easier to
understand. For example, using the `?` operator in some fns that return
an `Option` type.
Previously, the constants defined in `src/exit_codes` weren't being
used, and the constants for exit codes were being redefined in the
`internals` module.
This PR removes the exit code consts and instead uses an enum defined in
`src/exit_codes`. This centralizes the definitions of exit codes making
them easier to modify and keep track of.
Some tests throughout the codebase were just functions marked with the
`#[test]` macro. It is convention to have these test functions in a
`test` module with a compiler guard `cfg(test)`. This PR updates the
tests that aren't already setup like this to be in the `test` module.
Additionally, this PR also adds tests to the `exec` module to check the
remaining `Token` enum variations.
This upgrades the minimum required version of Rust to 1.29 in order to
fix#288.
See also:
- Rust compiler bug ticket: rust-lang/rust#50619
- Rust compiler PR with the fix: rust-lang/rust#50630closes#288
For muscle memory compatibility with `rg`. This variant will not show in
the help or in the program options, and is only checked if `--maxdepth`
is not specified.
Add a new `empty`/`e` type to search for empty files and/or directories.
To search for both empty files and directories, use one of the
following:
fd --type empty
fd -te
fd --type empty --type file --type directory
To search for empty files, use
fd --type empty --type file
fd -te -tf
To search for empty directories, use
fd --type empty --type directory
fd -te -td
closes#273
* Replace usage of `-exec` by `--exec`, except when it is used as a value that is given to `--exec/-exec/-x`.
* Limit usage of --exec option to single instance.
* Adding support for multiple paths. (panic)
- Started adding multiple file support
- fd panics with multiple files right now
* Moved the ctrlc handler to main.
- Moved the ctrlc handler to main so we can search multiple files
* Tests now allow custom directory setup
- TestEnv::new() now takes two arguments, the directories to create and
the files to create inside those directories.
* rust-fmt changes
* rust-fmt changes
* Moving code around, no need to do everything in one big loop
- PathDisplay was never actually used for anything, removed it during refactor of main
- Removed redundant logic for absolute paths
- Moved code placed needlessly inside a loop in the last commit outside of that loop.
* Moving code around, no need to do everything in one big loop
- PathDisplay was never actually used for anything, removed it during refactor of main
- Removed redundant logic for absolute paths
- Moved code placed needlessly inside a loop in the last commit outside of that loop.
* Removed commented code in testenv
* Refactored walk::scan to accept the path buffer vector. Using the ParallelWalker allows for multithreaded searching of multiple directories
* Moved ctrlc handler back into walker, it is only called once from main now.
* Moved the colored output check back to it's original place
* Removing shell-escape, not sure how it got added...
* Added test for `fd 'a.foo' test1` to show that a.foo is only found in the test1 and not the test2 direcotry
* Removing side effect from walk::scan, `dir_vec` is no longer a mutable reference and an iterator is being used instead.
* Running rustfmt to format code correctly
- Tidying up the build matrix
- All channels has TARGET env var
- Build against this targets:
- x86_64-unknown-linux-gnu
- x86_64-unknown-linux-musl
- i686-unknown-linux-gnu
- i686-unknown-linux-musl
- x86_64-apple-darwin
- Code formating check has it's own item in the build matrix
- Prevent target re-add error from rustup
- Incorporate the TARGET env var in the `install` and `script` stage
Previously, we were using the relative path to extract the search
string. For the current directory, the returned relative path was equal
to `""`. This is why the current directory did not show in the search
results (see #81).
This commit also changes the way that `--full-path` works, which was
previously working on relative paths. It seems more useful to search the
absolute path, though. Otherwise, search results could change just by
calling fd (with a given search path) from a different directory.
* Rewrite integration tests in Rust.
* Improve failure output for integration tests.
* Move TestEnv to separate module.
* Remove old integration tests script.
* Re-add integration test for subdirectory.
Color can now be forced on even when piping the output. Changed the
--no-color flag to --color which uses the same options that ripgrep
uses for --color (excluding ansi).
Closes#49.
- Add `--ignore-parent` option to override `--no-ignore-parent`, see #1958 (@tmchow)
- Add `--exact` option to match the entire filename exactly (literal, non-substring).
## Bugfixes
- Sanitize control characters and bidirectional override characters in filenames
when output goes to a terminal, to prevent terminal escape-sequence injection.
Also reject a placeholder as the executable for `--exec-batch`, while still
allowing it for `--exec`.
- Handle invalid working directories gracefully when using `--full-path`, see #1900 (@Xavrir).
- Fire the "search pattern contains a path separator" diagnostic for any pattern containing `/`, not just patterns that happen to name an existing directory. Preserves the legacy Windows behaviour that also flags native `\` separators when the pattern resolves to a real directory. See #1873.
- Also fire the "search pattern contains a path separator" diagnostic for `--and` patterns, not only the primary positional pattern. `--and` patterns are matched against the file name just like the primary pattern, so a path separator in them silently returned zero results. See #1873.
- Fix bug where passing "-" as a directory argument didn't actually search that directory, see #849 (@Sean-Kenneth-Doherty).
- Fix panic when `--changed-before`/`--changed-within` is given an out-of-range `@` Unix timestamp; the value is now rejected gracefully, see #2081 (@nikolauspschuetz).
# 10.4.2
## Bugfixes
- Fixed performance regression due to `--ignore-contain`; see #1913 and #1914
# 10.4.1
This is just a re-release of 10.4.0 due to an issue with the 10.4.0 release.
# 10.4.0
## Features
- Add `--ignore-contain` option to ignore directories containing a named entry (e.g. to ignore [`CACHEDIR.TAG`](https://bford.info/cachedir/)); see #1727 (@fischman).
## Bugfixes
- Fix Windows hyperlink generation for paths with spaces. (#1872)
-`--print0` combined with `--exec` will now print a `\0` between the output of each entry. Note that if there are multiple instances
of `--exec`, the `\0` will be between each _set_ of commands, _not_ between each individual command run. Fixes #1797.
- Several bugs were fixed by an update to the `ignore` library used for handling ignore rules
-#1506
-#1667
-#1813
- Fix completions for alias `fdfind` in deb release, see #1888 (@skane-lukas)
## Changes
- Minimum required rust version has been increased to 1.90.0. Notably, this means dropping fully support for intel Mac and Windows 7.
- Statically link the CRT for MSVC builds via Cargo config to avoid runtime DLL dependencies, see #1874 (@FidelSch)
# 10.3.0
## Features
- Add a hidden `--mindepth` alias for `--min-depth`. (#1617)
## Bugfixes
## Changes
- Replace `humantime` crate and `chrono` crate with `jiff` crate, see #1690 (@sorairolake). This has some small changes to the
way dates given to options such `--changed-within` and `--changed-before` including:
- 'M' no longer means "month", as that could be confusing with minutes. Use "mo", "mos", "month" or "months" instead.
- month and year now account for variability in the calander rather than being a hard-coded number of seconds. That is probably
what you would expect, but it is a slight change in behavior.
- aarch64 Windows was added to CI and release artifacts
- Many dependencies were updated
- Better support building on Illumos (there is no automated testing, but some known issues were fixed)
## Other
This will be the last release that has been tested on x86_64 Mac OS, since GitHub is
dropping support for runners with that hardware.
It may also be the last release to use a version of Rust with tier-1 support for
x86_64/intel Macs and Windows 7.
# 10.2.0
## Features
- Add --hyperlink option to add OSC 8 hyperlinks to output
## Bugfixes
## Changes
- Build windows releases with rust 1.77 so windows 7 is still supported
- Deb packages now include symlink for fdfind to be more consistent with official packages
## Other
# 10.1.0
## Features
- Allow passing an optional argument to `--strip-cwd-prefix` of "always", "never", or "auto". to force whether the cwd prefix is stripped or not.
- Add a `--format` option which allows using a format template for direct ouput similar to the template used for `--exec`. (#1043)
## Bugfixes
- Fix aarch64 page size again. This time it should actually work. (#1085, #1549) (@tavianator)
## Other
- aarch64-apple-darwin target added to builds on the release page. Note that this is a tier 2 rust target.
# v10.0.0
## Features
- Add `dir` as an alias to `directory` when using `-t` \ `--type`, see #1460 and #1464 (@Ato2207).
- Add support for @%s date format in time filters similar to GNU date (seconds since Unix epoch for --older/--newer), see #1493 (@nabellows)
- Breaking: No longer automatically ignore `.git` when using `--hidden` with vcs ignore enabled. This reverts the change in v9.0.0. While this feature
was often useful, it also broke some existing workflows, and there wasn't a good way to opt out of it. And there isn't really a good way for us to add
a way to opt out of it. And you can easily get similar behavior by adding `.git/` to your global fdignore file.
See #1457.
## Bugfixes
- Respect NO_COLOR environment variable with `--list-details` option. (#1455)
- Fix bug that would cause hidden files to be included despite gitignore rules
if search path is "." (#1461, BurntSushi/ripgrep#2711).
- aarch64 builds now use 64k page sizes with jemalloc. This fixes issues on some systems, such as ARM Macs that
have a larger system page size than the system that the binary was built on. (#1547)
- Address [CVE-2024-24576](https://blog.rust-lang.org/2024/04/09/cve-2024-24576.html), by increasing minimum rust version.
## Changes
- Minimum supported rust version is now 1.77.2
# v9.0.0
## Performance
- Performance has been *significantly improved*, both due to optimizations in the underlying `ignore`
crate (#1429), and in `fd` itself (#1422, #1408, #1362) - @tavianator.
[Benchmarks results](https://gist.github.com/tavianator/32edbe052f33ef60570cf5456b59de81) show gains
of 6-8x for full traversals of smaller directories (100k files) and up to 13x for larger directories (1M files).
- The default number of threads is now constrained to be at most 64. This should improve startup time on
systems with many CPU cores. (#1203, #1410, #1412, #1431) - @tmccombs and @tavianator
- New flushing behavior when writing output to stdout, providing better performance for TTY and non-TTY
use cases, see #1452 and #1313 (@tavianator).
## Features
- Support character and block device file types, see #1213 and #1336 (@cgzones)
- Breaking: `.git/` is now ignored by default when using `--hidden` / `-H`, use `--no-ignore` / `-I` or
`--no-ignore-vcs` to override, see #1387 and #1396 (@skoriop)
## Bugfixes
- Fix `NO_COLOR` support, see #1421 (@acuteenvy)
## Other
- Fixed documentation typos, see #1409 (@marcospb19)
## Thanks
Special thanks to @tavianator for his incredible work on performance in the `ignore` crate and `fd` itself.
# v8.7.1
## Bugfixes
-`-1` properly conflicts with the exec family of options.
-`--max-results` overrides `-1`
-`--quiet` properly conflicts with the exec family of options. This used to be the case, but broke during the switch to clap-derive
-`--changed-within` now accepts a space as well as a "T" as the separator between date and time (due to update of chrono dependency)
## Other
- Many dependencies were updated
- Some documentation was updated and fixed
# v8.7.0
## Features
- Add flag --no-require-git to always respect gitignore files, see #1216 (@vegerot)
## Bugfixes
- Fix logic for when to use global ignore file. There was a bug where the only case where the
global ignore file wasn't processed was if `--no-ignore` was passed, but neither `--unrestricted`
nor `--no-global-ignore-file` is passed. See #1209
# v8.6.0
## Features
- New `--and <pattern>` option to add additional patterns that must also be matched. See #315
and #1139 (@Uthar)
- Added `--changed-after` as alias for `--changed-within`, to have a name consistent with `--changed-before`.
## Changes
- Breaking: On Unix-like systems, `--type executable` now additionally checks if
the file is executable by the current user, see #1106 and #1169 (@ptipiak)
## Bugfixes
- Use fd instead of fd.exe for Powershell completions (when completions are generated on windows)
## Other
# v8.5.3
## Bugfixes
- Fix completion generation to not include full path of fd command
- Fix build error if completions feature is disabled
# v8.5.2
## Bugfixes
- Fix --owner option value parsing, see #1163 and #1164 (@tmccombs)
# v8.5.1
## Bugfixes
- Fix --threads/-j option value parsing, see #1160 and #1162 (@sharkdp)
# v8.5.0
## Features
-`--type executable`/`-t` now works on Windows, see #1051 and #1061 (@tavianator)
## Bugfixes
- Fixed differences between piped / non-piped output. This changes `fd`s behavior back to what we
had before 8.3.0, i.e. there will be no leading `./` prefixes, unless `--exec`/`-x`,
`--exec-batch`/`-X`, or `--print0`/`-0` are used. `--strip-cwd-prefix` can be used to strip that
prefix in those cases. See #1046, #1115, and #1121 (@tavianator)
-`fd` could previously crash with a panic due to a race condition in Rusts standard library
(see https://github.com/rust-lang/rust/issues/39364). This has been fixed by switching to a different
message passing implementation, see #1060 and #1146 (@tavianator)
-`fd`s memory usage will not grow unboundedly on huge directory trees, see #1146 (@tavianator)
- fd returns an error when current working directory does not exist while a search path is
specified, see #1072 (@vijfhoek)
- Improved "command not found" error message, see #1083 and #1109 (@themkat)
- Preserve command exit codes when using `--exec-batch`, see #1136 and #1137 (@amesgen)
## Changes
- No leading `./` prefix for non-interactive results, see above.
- fd now colorizes paths in parallel, significantly improving performance, see #1148 (@tavianator)
- fd can now avoid `stat` syscalls even when colorizing paths, as long as the color scheme doesn't
require metadata, see #1148 (@tavianator)
- The statically linked `musl` versions of `fd` now use `jmalloc`, leading to a significant performance
improvement, see #1062 (@tavianator)
## Other
- Added link back to GitHub in man page and `--help` text, see #1086 (@scottchiefbaker)
- Major update in how `fd` handles command line options internally, see #1067 (@tmccombs)
# v8.4.0
## Features
- Support multiple `--exec <cmd>` instances, see #406 and #960 (@tmccombs)
## Bugfixes
- "Argument list too long" errors can not appear anymore when using `--exec-batch`/`-X`, as the command invocations are automatically batched at the maximum possible size, even if `--batch-size` is not given. See #410 and #1020 (@tavianator)
## Changes
- Directories are now printed with an additional path separator at the end: `foo/bar/`, see #436 and #812 (@yyogo)
- The `-u` flag was changed to be equivalent to `-HI` (previously, a single `-u` was only equivalent to `-I`). Additional `-u` flags are still allowed, but ignored. See #840 and #986 (@jacksontheel)
## Other
- Added installation instructions for RHEL8, see #989 (@ethsol)
# v8.3.2
## Bugfixes
- Invalid absolute path on windows when searching from the drive root, see #931 and #936 (@gbarta)
# v8.3.1
## Bugfixes
- Stop implying `--no-ignore-parent` when `--no-vcs-ignore` is supplied, see #907, #901, #908 (@tmccombs)
- fd no longer waits for the whole traversal if the only matches arrive within max_buffer_time, see #868 and #895 (@tavianator)
-`--max-results=1` now immediately quits after the first result, see #867
-`fd -h` does not panic anymore when stdout is closed, see #897
## Changes
- Disable jemalloc on FreeBSD, see #896 (@xanderio)
- Updated man page, see #912 (@rlue)
- Updated zsh completions, see #932 (@tmccombs)
# v8.3.0
## Performance improvements
- Colorized output is now significantly faster, see #720 and #853 (@tavianator)
- Writing to stdout is now buffered if the output does not go to a TTY. This increases performance
when the output of `fd` is piped to another program or to a file, see #885 (@tmccombs, original
implementation by @sourlemon207)
- File metadata is now cached between the different filters that require it (e.g. `--owner`,
`--size`), reducing the number of `stat` syscalls when multiple filters are used; see #863
(@tavianator, original implementation by @alexmaco)
## Features
- Don't buffer command output from `--exec` when using a single thread. See #522
- Add new `-q, --quiet` flag, see #303 (@Asha20)
- Add new `--no-ignore-parent` flag, see #787 (@will459)
- Add new `--batch-size` flag, see #410 (@devonhollowood)
- Add opposing command-line options, see #595 (@Asha20)
- Add support for more filesystem indicators in `LS_COLORS`, see
- Always show the `./` prefix for search results unless the output is a TTY or `--strip-cwd-prefix` is set, see #760 and #861 (@jcaplan)
- Set default path separator to `/` in MSYS, see #537 and #730 (@aswild)
- fd cannot search files under a RAM disk, see #752
- fd doesn't show substituted drive on Windows, see #365
- Properly handle write errors to devices that are full, see #737
- Use local time zone for time functions (`--change-newer-than`, `--change-older-than`), see #631 (@jacobmischka)
- Support `--list-details` on more platforms (like BusyBox), see #783
- The filters `--owner`, `--size`, and `--changed-{within,before}` now apply to symbolic links
themselves, rather than the link target, except when `--follow` is specified; see #863
- Change time comparisons to be exclusive, see #794 (@jacobmischka)
## Changes
- Apply custom `--path-separator` to commands run with `--exec(-batch)` and `--list-details`, see #697 (@aswild)
## Other
- Many documentation updates
# v8.2.1
No functional changes with respect to v8.2.0. Bugfix in the release process.
# v8.2.0
## Features
- Add new `--prune` flag, see #535 (@reima)
- Improved the usability of the time-based options, see #624 and #645 (@gorogoroumaru)
- Add support for exact file sizes in the `--size` filter, see #669 and #696 (@Rogach)
-`fd` now prints an error message if the search pattern requires a leading dot but
`--hidden` is not enabled (Unix only), see #615
## Bugfixes
- Avoid panic when performing limited searches in directories with restricted permissions, see #678
- Invalid numeric command-line arguments are silently ignored, see #675
- Disable jemalloc on Android, see #662
- The `--help` text will be colorless if `NO_COLOR` has been set, see #600 (@xanonid)
## Changes
- If `LS_COLORS` is not set (e.g. on Windows), we now provide a more comprehensive default which
includes much more filetypes, see #604 and #682 (mjsir911).
## Other
- Added `zsh` completion files, see #654 and #189 (@smancill)
# v8.1.1
## Bugfixes
- Support colored output on older Windows versions if either (1) `--color=always` is set or (2) the `TERM` environment variable is set. See #469
# v8.1.0
## Features
- Add new `--owner [user][:group]` filter. See #307 (pull #581) (@alexmaco)
- Add support for a global ignore file (`~/.config/fd/ignore` on Unix), see #575 (@soedirgo)
- Do not exit immediately if one of the search paths is missing, see #587 (@DJRHails)
## Bugfixes
- Reverted a change from fd 8.0 that enabled colors on all Windows terminals (see below) in order to support older Windows versions again, see #577. Unfortunately, this re-opens #469
- Fix segfault caused by jemalloc on macOS Catalina, see #498
- Fix `--glob` behavior with empty pattern, see #579 (@SeamusConnor)
- Fix `--list-details` on FreeBSD, DragonFly BSD, OpenBSD and NetBSD. See #573 (@t6)
## Changes
- Updated documentation for `--size`, see #584
# v8.0.0
## Features
- Add a new `-l`/`--list-details` option to show more details about the search results. This is
basically an alias for `--exec-batch ls -l` with some additional `ls` options.
This can be used in order to:
* see metadata like permissions, owner, file size, modification times (#491)
* see symlink targets (#482)
* achieve a deterministic output order (#324, #196, #159)
- Add a new `--max-results=<count>` option to limit the number of search results, see #472, #476 and #555
This can be useful to speed up searches in cases where you know that there are only N results.
Using this option is also (slightly) faster than piping to `head -n <count>` where `fd` can only
exit when it finds the search results `<count> + 1`.
- Add the alias `-1` for `--max-results=1`, see #561. (@SimplyDanny).
- Add new `--type socket` and `--type pipe` filters, see #511.
- Add new `--min-depth <depth>` and `--exact-depth <depth>` options in addition to the existing option
to limit the maximum depth. See #404.
- Support additional ANSI font styles in `LS_COLORS`: faint, slow blink, rapid blink, dimmed, hidden and strikethrough.
## Bugfixes
- Preserve non-UTF8 filenames: invalid UTF-8 filenames are now properly passed to child-processes
when using `--exec`, `--exec-batch` or `--list-details`. In `fd`'s output, we replace non-UTF-8
sequences with the "�" character. However, if the output of `fd` goes to another process, we
print the actual bytes of the filename. For more details, see #558 and #295.
-`LS_COLORS` entries with unsupported font styles are not completely ignored, see #552
## Changes
- Colored output will now be enabled by default on older Windows versions.
This allows the use of colored output if the terminal supports it (e.g.
MinTTY, Git Bash). On the other hand, this will be a regression for users
on older Windows versions with terminals that do not support ANSI escape
sequences. Affected users can use an alias `fd="fd --color=never"` to
continue using `fd` without colors. There is no change of behavior for
Windows 10. See #469.
- When using `--glob` in combination with `--full-path`, a `*` character does not match a path
separation character (`/` or `\\`) anymore. You can use `**` for that. This allows things like
`fd -p -g '/some/base/path/*/*/*.txt'` which would previously match to arbitrary depths (instead
of exactly two folders below `/some/base/path`. See #404.
- "Legacy" support to use `fd -exec` (with a single dash) has been removed. Use `fd -x` or
`fd --exec` instead.
- Overall improved error handling and error messages.
## Other
- Korean translation of the README, see: [한국어](https://github.com/spearkkk/fd-kor) (@spearkkk)
# v7.5.0
## Features
- Added `--one-file-system` (aliases: `--mount`, `--xdev`) to not cross file system boundaries on Unix and Windows, see #507 (@FallenWarrior2k).
- Added `--base-directory` to change the working directory in which `fd` is run, see #509 and #475 (@hajdamak).
-`fd` will not use colored output if the `NO_COLOR` environment variable is set, see #550 and #551 (@metadave).
-`fd --exec` will return exit code 1 if one of the executed commands fails, see #526 and #531 (@fusillicode and @Giuffre)
## Bug Fixes
- Fixed 'command not found' error when using zsh completion, see #487 (@barskern).
-`fd -L` should include broken symlinks, see #357 and #497 (@tommilligan, @neersighted and @sharkdp)
- Display directories even if we don't have permission to enter, see #437 (@sharkdp)
## Changes
- A flag can now be passed multiple times without producing an error, see #488 and #496 (@rootbid).
- Search results are sorted when using the `-X` option to match the behaviour of piping to `xargs`, see #441 and #524 (@Marcoleni@crash-g).
# v7.4.0
## Performance improvements
- Reduce number of `stat` syscalls, improving the performance for searches where file metadata is
required (`--type`, `--size`, `--changed-within`, …), see #434 (@tavianator)
- Use jemalloc by default, improving the performance for almost all searches, see #481. Note that
Windows and `*musl*` builds do not profit from this.
## Features
- Added a new `-g`/`--glob` option to switch to glob-based searches (instead of regular expression
based searches). This is accompanied by a new `--regex` option that can be used to switch back,
if users want to `alias fd="fd --glob"`. See #284
- Added a new `--path-separator <sep>` option which can be useful for Windows users who
want/need `fd` to use `/` instead of `\`, see #428 and #153 (@mookid)
- Added support for hidden files on Windows, see #379
- When `fd` is run with the `--exec-batch`/`-X` option, it now exposes the exit status of the
command that was run, see #333.
- Exit immediately when Ctrl-C has been pressed twice, see #423
## Bugfixes
- Make `--changed-within`/`--changed-before` work for directories, see #470
## Other
- Pre-built `fd` binaries should now be available for `armhf` targets, see #457 (@detly)
-`fd` is now available on Alpine Linux, see #451 (@5paceToast)
-`fd` is now in the officla FreeBSD repositories, see #412 (@t6)
- Added OpenBSD install instructions, see #421 (@evitalis)
- Added metadata to the Debian package, see #416 (@cathalgarvey)
-`fd` can be installed via npm, see #438 (@pablopunk)
# v7.3.0
## Features
- New `--exec-batch <cmd>`/`-X <cmd>` option for batch execution of commands, see #360 (@kimsnj).
This allows you to do things like:
``` bash
fd … -X vim # open all search results in vim (or any other editor)
fd … -X ls -l # view detailed stats about the search results with 'ls'
fd -e svg -X inkscape # open all SVG files in Inkscape
```
- Support for 24-bit color codes (when specified via `LS_COLORS`) as well as
different font styles (bold, italic, underline).
## Changes
- A few performance improvements, in particular when printing lots of colorized
results to the console, see #370
- The `LS_COLORS` handling has been "outsourced" to a separate crate (https://github.com/sharkdp/lscolors) that is now being used by other tools as well: [fselect](https://github.com/jhspetersson/fselect), [lsd](https://github.com/Peltoche/lsd/pull/84). For details, see #363.
## Other
- `fd` will be available in Ubuntu Disco DIngo (19.04), see #373 (@sylvestre)
- This release should come with a static ARM binary (`arm-unknown-linux-musleabihf`), see #320 (@duncanfinney)
- Various documentation improvements, see #389
## Thanks
Special thanks to @alexmaco for his awesome work on refactoring and code improvements! (see #401, #398, and #383)
# v7.2.0
## Features
* Added support for filtering by file modification time by adding two new options `--changed-before <date|duration>` and `--changed-within <..>`. For more details, see the `--help` text, the man page, the relevant issue #165 and the PR #339 (@kimsnj)
* Added `--show-errors` option to enable the display of filesystem error messages such as "permission denied", see #311 (@psinghal20 and @majecty)
* Added `--maxdepth` as a (hidden) alias for `--max-depth`, see #323 (@mqudsi)
* Added `--search-path` option which can be supplied to replace the positional `path` argument at any position.
## Changes
* Loosen strict handling of missing `--ignore-file`, see #280 (@psinghal20)
* Re-enabled `.ignore` files, see #156.
## Bugfixes
* `fd` could previously get stuck when run from the root directory in the
presence of zombie processes. This curious bug has been fixed in Rust 1.29 and higher. For more details, see #288, [rust-lang/rust#50619](https://github.com/rust-lang/rust/issues/50619) and [the fix](https://github.com/rust-lang/rust/pull/50630)
## Other
* `fd` has officially landed in Debian! See #345 for details. Thanks goes to @sylvestre, @paride and possibly others I don't know about.
* Added Chinese translation of README (@chinanf-boy)
## Thanks
A special thanks goes to @joshleeb for his amazing improvements throughout
the code base (new tests, refactoring work and various other things)!
# v7.1.0
## Features
* Added `--size` filter option, see #276 (@stevepentland, @JonathanxD and @alexmaco)
* Added `--type empty` (or `-t e`) to search for empty files and/or directories, see #273
## Changes
* With the new version, `.gitignore` files will only be respected in Git repositories, not outside.
* A few performance improvements for `--type` searches, see 641976cf7ad311ba741571ca8b7f02b2654b6955 and 50a2bab5cd52d26d4a3bc786885a2c270ed3b227
## Other
* Starting with this release, we will offer pre-built ARM binaries, see #244
* Added instructions on how to use `fd` with `emacs`, see #282 (@redguardtoo)
* `fd` is now in the official openSUSE repositories, see #275 (@avindra)
* `fd` is now available via MacPorts, see #291 (@raimue)
# v7.0.0
## Features
* Added `--type executable` (or `-t x`) to search for executable files only, see #246 (@PramodBisht)
* Added support for `.fdignore` files, see #156 and #241.
* Added `--ignore-file` option to add custom ignore files, see #156.
* Suggest `--fixed-strings` on invalid regular expressions, see #234 (@PramodBisht)
* Detect when user supplied path instead of pattern, see #235.
## Changes
* `.ignore` and `.rgignore` files are not parsed anymore. Use `.fdignore` files
or add custom files via `--ignore-file` instead.
* Updated to `regex-syntax` 0.5 (@cuviper)
## Bugfixes
* Properly normalize absolute paths, see #268
* Invalid utf8 filenames displayed when `-e` is used, see #250
* If `--type` is used, fifos/sockets/etc. are always shown, see #260
## Other
* Packaging:
* The Arch Linux package is now simply called `fd`.
* There is now a `fd` ebuild for Gentoo Linux.
* There is a `scoop` package for `fd` (Windows).
* There is a `Chocolatey` package for `fd` (Windows).
* There is a Fedora `copr` package for `fd`.
# v6.3.0
## Features
* Files with multiple extensions can now be found via `--extension`/`-e`, see #214 (@althonos)
``` bash
> fd -e tar.gz
```
* Added new `-F`/`--fixed-strings`/`--literal` option that treats the pattern as a literal string instead of a regular expression, see #157
``` bash
> fd -F 'file(1).txt'
```
* Allow `-exec` to work as `--exec`, see #226 (@stevepentland)
## Bugfixes
* Fixed `Ctrl-C` handling when using `--exec`, see #224 (@Doxterpepper)
* Fixed wrong file owner for files in deb package, see #213
## Other
* Replaced old gif by a fancy new SVG screencast (@marionebl)
* Updated [benchmark results](https://github.com/sharkdp/fd#benchmark) (fd has become faster in the meantime!). There is a new repository that hosts several benchmarking scripts for fd: https://github.com/sharkdp/fd-benchmarks
# v6.2.0
## Features
* Support for filtering by multiple file extensions and multiple file types, see #199 and #177
(@tkadur).
For example, it's possible to search for C++ source or header files:
``` bash
> fd -e cpp -e c -e cxx -e h pattern
```
## Changes
* The size of the output buffer (for sorting search results) is now limited to 1000 entries. This
improves the search speed significantly if there are a lot of results, see #191 (@sharkdp).
## Bugfixes
* Fix a bug where long-running searches could not be killed via Ctrl-C, see #210 (@Doxterpepper)
* fd's exit codes are now in accordance with Unix standards, see #201 (@Doxterpepper)
## Other
* Bash, zsh and fish completion should now work with the Ubuntu `.deb` packages, see #195 and #209
(@tmccombs and @sharkdp)
* There is a new section on how to set up `fzf` to use `fd` in the
[README](https://github.com/sharkdp/fd#using-fd-with-fzf), see #168.
# v6.1.0
## Features
* Support for multiple search paths, see #166 (@Doxterpepper)
* Added `--no-ignore-vcs` option to disable `.gitignore` and other VCS ignore files,
without disabling `.ignore` files - see #156 (@ptzz).
## Bugfixes
* Handle terminal signals, see #128 (@Doxterpepper)
* Fixed hang on `--exec` when user input was required, see #178 and #193 (@reima)
## Other
* Debian packages are now created via Travis CI and should be available for this and all
future releases (@tmccombs).
* fd is now available on Void Linux (@maxice8)
* The minimum required Rust version is now 1.20
## Thanks
@Doxterpepper deserves a special mention for his great work that is included in this release and
for the support in ticket discussions and concerning Travis CI fixes. Thank you very much!
Thanks also go out to @tmccombs for the work on Debian packages and for reviewing a lot of pull requests!
# v6.0.0
## Changes
- The `--exec`/`-x` option does not spawn an intermediate shell anymore. This improves the
performance of parallel command execution and fixes a whole class of (present and potentially
future) problems with shell escaping. The drawback is that shell commands cannot directly be
called with `--exec`. See #155 for the full discussion. These changes have been implemented by
@reima (Thanks!).
## Bugfixes
- `--exec` does not escape cmd.exe metacharacters on Windows (see #155, as above).
## Other
* *fd* is now available in the FreeBSD ports (@andoriyu)
* The minimal `rustc` version is now checked when building with `cargo`, see #164 (@matematikaadit)
* The output directory for the shell completion files is created if it does not exist (@andoriyu)
# v5.0.0
## Features
* Added new `--exec`, `-x` option for parallel command execution (@mmstick, see #84 and #116). See the corresponding [README section](https://github.com/sharkdp/fd#parallel-command-execution) for an introduction.
* Auto-disable color output on unsupported Windows shells like `cmd.exe` (@iology, see #129)
* Added the `--exclude`, `-X` option to suppress certain files/directories in the search results
(see #89).
* Added ripgrep aliases `-u` and `-uu` for `--no-ignore` and `--no-ignore --hidden`, respectively
(@unsignedint, see #92)
* Added `-i`, `--ignore-case` (@iology, see #95)
* Made smart case really smart (@reima, see #103)
* Added RedoxOS support (@goyox86, see #131)
## Changes
* The dot `.` can now match newlines in file names (@iology, see #111)
* The short `--type` argument for symlinks has been changed from `s` to `l` (@jcpetkovich, see #83)
## Bugfixes
* Various improvements in root-path and symlink handling (@iology, see #82, #107, and #113)
* Fixed absolute path handling on Windows (@reima, #93)
* Fixed: current directory not included when using relative path (see #81)
* Fixed `--type` behavior for unknown file types (@iology, see #150)
* Some fixes around `--exec` (@iology, see #142)
## Other
* Major updates and bugfixes to our continuous integration and deployment tooling on Travis
(@matematikaadit, see #149, #145, #133)
* Code style improvements & automatic style checking via `rustfmt` on Travis (@Detegr, see #99)
* Added a man page (@pickfire, see #77)
* *fd* has been relicensed under the dual license MIT/Apache-2.0 (@Detegr, see #105)
* Major refactorings and code improvements (Big thanks to @gsquire, @reima, @iology)
* First version of [`CONTRIBUTING`](https://github.com/sharkdp/fd/blob/master/CONTRIBUTING.md) guidelines
* There is now a Nix package (@mehandes)
* *fd* is now in the official Arch Linux repos (@cassava)
* Improved tooling around shell completion files (@ImbaKnugel, see #124)
* Updated tutorial in the [`README`](https://github.com/sharkdp/fd/blob/master/README.md)
* The minimum required version of Rust has been bumped to 1.19.
## Thanks
A *lot* of things have happened since the last release and I'd like to thank all contributors for their great support. I'd also like to thank those that have contributed by reporting bugs and by posting feature requests.
I'd also like to take this chance to say a special Thank You to a few people that have stood out in one way or another: To @iology, for contributing a multitude of bugfixes, improvements and new features. To @reima and @Detegr for their continuing great support. To @mmstick, for implementing the most advanced new feature of *fd*. And to @matematikaadit for the CI/tooling upgrades.
# v4.0.0
## Features
* Added filtering by file extension, for example `fd -e txt`, see #56 (@reima)
* Add option to force colored output: `--color always`, see #49 (@Detegr)
* Generate Shell completions for Bash, ZSH, Fish and Powershell, see #64 (@ImbaKnugel)
* Better & extended `--help` text (@abaez and @Detegr)
* Proper Windows support, see #70
## Changes
* The integration tests have been re-written in Rust :sparkles:, making them platform-independent and easily callable via `cargo test` - see #65 (many thanks to @reima!)
* New tutorial in the README (@deg4uss3r)
* Reduced number of `stat` syscalls for each result from 3 to 1, see #36.
* Enabled Appveyor CI
# v3.1.0
## Features
- Added file type filtering, e.g. `find --type directory` or `find -t f` (@exitium)
# v3.0.0
## Features
- Directories are now traversed in parallel, leading to significant performance improvements (see [benchmarks](https://github.com/sharkdp/fd#benchmark))
- Added `--print0` option (@michaelmior)
- Added AUR packages (@wezm)
## Changes
- Changed short flag for `--follow` from `-f` to `-L` (consistency with `ripgrep`)
# v2.0.0
* Changed `--sensitive` to `--case-sensitive`
* Changed `--absolute` to `--absolute-path`
* Throw an error if root directory is not existent, see #39
* Use absolute paths if the root dir is an absolute path, see #40
* Handle invalid UTF-8, see #34 #38
* Support `-V`, `--version` by switching from `getopts` to `clap`.
Misc:
* It's now possible to install `fd` via homebrew on macOS: `brew install fd`.
# v1.1.0
- Windows compatibility (@sebasv), see #29 #35
- Safely exit on broken output pipes (e.g.: usage with `head`, `tail`, ..), see #24
- Backport for rust 1.16, see #23
# v1.0.0
* Respect `.(git)ignore` files
* Use `LS_COLORS` environment variable directly, instead of `~/.dir_colors` file.
* Added unit and integration tests
* Added optional second argument (search path)
# v0.3.0
- Parse dircolors files, closes #20
- Colorize each path component, closes #19
- Add short command line option for --hidden, see #18
To really search *all* files and directories, simply combine the hidden and ignore features to show
everything (`-HI`) or use `-u`/`--unrestricted`.
### 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.
```bash
> fd -u -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:
``` bash
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`:
``` bash
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.
Any positional arguments after `-x` belong to the command template, not to `fd` itself. If you
also want to pass a pattern or search path, put `-x` last:
``` bash
fd pattern path -x echo
```
Find all `test_*.py` files and open them in your favorite editor:
``` bash
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:
``` bash
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](https://github.com/BurntSushi/ripgrep/) (`rg`) in order to search within a certain class of files, like all C++ source files:
```bash
fd -e cpp -e cxx -e h -e hpp -X rg 'std::cout'
```
Convert all `*.jpg` files to `*.png` files:
``` bash
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.
The terminal output of commands run from parallel threads using `-x` will not be interlaced or garbled,
so `fd -x` can be used to rudimentarily parallelize a task run over many files.
An example of this is calculating the checksum of each individual file within a directory.
``` bash
fd -tf -x md5sum > file_checksums.txt
```
#### 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 `\;`.
For example, `fd -x echo \; pattern path` treats `pattern path` as `fd` arguments instead of
passing them to `echo`. In practice, it is often clearer to write `fd pattern path -x echo`.
The syntax for generating commands is similar to that of [GNU Parallel](https://www.gnu.org/software/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:
``` bash
> fd -H -E .git …
```
We can also use this to skip mounted directories:
``` bash
> fd -E /mnt/external-drive …
```
.. or to skip certain file types:
``` bash
> 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:
``` bash
> 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.
You may wish to include `.git/` in your `fd/ignore` file so that `.git` directories, and their contents
are not included in output if you use the `--hidden` option.
### 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:
``` bash
> fd -H '^\.DS_Store$' -tf -X rm
```
If you are unsure, always call `fd` without `-X rm` first. Alternatively, use `rm`s "interactive"
option:
``` bash
> 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 `rm`s `--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 [OPTIONS] [pattern [path]...]
Arguments:
[pattern] the search pattern (a regular expression, unless '--glob' is used; optional)
[path]... the root directories for the filesystem search (optional)
Options:
-H, --hidden Search hidden files and directories
-I, --no-ignore Do not respect .(git|fd)ignore files
For more details, see the [Tips section](https://github.com/junegunn/fzf#tips) of the fzf README.
### Using fd with `rofi`
[*rofi*](https://github.com/davatorium/rofi) is a graphical launch menu application that is able to create menus by reading from *stdin*. Piping `fd` output into `rofi`s `-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.
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](https://github.com/technomancy/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` as a file-tree you can use the `tree` command with
`--fromfile`:
```bash
❯ fd | tree --fromfile
```
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:
```bash
❯ fd --extension rs | tree --fromfile
.
├── build.rs
└── src
├── app.rs
└── error.rs
```
On bash and similar you can simply create an alias:
```bash
❯ alias as-tree='tree --fromfile'
```
### Using fd with `xargs` or `parallel`
Note that `fd` has a builtin feature for [command execution](#command-execution) with
its `-x`/`--exec` and `-X`/`--exec-batch` options. If you prefer, you can still use
it in combination with `xargs`:
``` bash
> 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.
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`.
Note that the .deb packages on the release page for this project still name the executable `fd`.
### On Fedora
Starting with Fedora 28, you can install `fd` from the official package sources:
``` bash
dnf install fd-find
```
### On Alpine Linux
You can install [the fd package](https://pkgs.alpinelinux.org/packages?name=fd)
from the official sources, provided you have the appropriate repository enabled:
```
apk add fd
```
### On Arch Linux
You can install [the fd package](https://www.archlinux.org/packages/extra/x86_64/fd/) from the official repos:
```
pacman -S fd
```
You can also install fd [from the AUR](https://aur.archlinux.org/packages/fd-git).
### On Gentoo Linux
You can use [the fd ebuild](https://packages.gentoo.org/packages/sys-apps/fd) from the official repo:
```
emerge -av fd
```
### On openSUSE Linux
You can install [the fd package](https://software.opensuse.org/package/fd) from the official repo:
```
zypper in fd
```
### On Void Linux
You can install `fd` via xbps-install:
```
xbps-install -S fd
```
### On ALT Linux
You can install [the fd package](https://packages.altlinux.org/en/sisyphus/srpms/fd/) from the official repo:
```
apt-get install fd
```
### On Solus
You can install [the fd package](https://github.com/getsolus/packages/tree/main/packages/f/fd) from the official repo:
```
eopkg install fd
```
### On RedHat Enterprise Linux (RHEL) 8/9/10, Almalinux 8/9/10, EuroLinux 8/9 or Rocky Linux 8/9/10
You can install [the `fd` package](https://copr.fedorainfracloud.org/coprs/tkbcopr/fd/) from Fedora Copr.
```bash
dnf copr enable tkbcopr/fd
dnf install fd
```
A different version using the [slower](https://github.com/sharkdp/fd/pull/481#issuecomment-534494592) malloc [instead of jemalloc](https://bugzilla.redhat.com/show_bug.cgi?id=2216193#c1) is also available from the EPEL8/9 repo as the package `fd-find`.
### On macOS
You can install `fd` with [Homebrew](https://formulae.brew.sh/formula/fd):
```
brew install fd
```
On **Arch Linux**, you can install the AUR package [fd-rs](https://aur.archlinux.org/packages/fd-rs/) (for the stable version) or [fd-rs-git](https://aur.archlinux.org/packages/fd-rs-git/) (for the current master) via yaourt, or manually:
… or with MacPorts:
```
git clone https://aur.archlinux.org/fd-rs.git
cd fd-rs
makepkg -si
port install fd
```
### On Windows
You can download pre-built binaries from the [release page](https://github.com/sharkdp/fd/releases).
Alternatively, you can install `fd` via [Scoop](http://scoop.sh):
```
scoop install fd
```
Or via [Chocolatey](https://chocolatey.org):
```
choco install fd
```
Or via [Winget](https://learn.microsoft.com/en-us/windows/package-manager/):
```
winget install sharkdp.fd
```
### On GuixOS
You can install [the fd package](https://guix.gnu.org/en/packages/fd-8.1.1/) from the official repo:
```
guix install fd
```
### On Mise
You can use [mise](https://github.com/jdx/mise) to install `fd` with a command like this:
```
mise use -g fd@latest
```
### On NixOS / via Nix
You can use the [Nix package manager](https://nixos.org/nix/) to install `fd`:
```
nix-env -i fd
```
### Via Flox
You can use [Flox](https://flox.dev) to install `fd` into a Flox environment:
```
flox install fd
```
### On FreeBSD
You can install [the fd-find package](https://www.freshports.org/sysutils/fd) from the official repo:
```
pkg install fd-find
```
### From npm
On Linux and macOS, you can install the [fd-find](https://npm.im/fd-find) package:
```
npm install -g fd-find
```
### From source
With Rust's package manager [cargo](https://github.com/rust-lang/cargo), you can install *fd* via:
```
cargo install fd-find
```
Note that rust version *1.90.0* or later is required.
`make` is also needed for the build.
### From binaries
The [release page](https://github.com/sharkdp/fd/releases) includes precompiled binaries for Linux, macOS and Windows. Statically-linked binaries are also available: look for archives with `musl` in the file name.
Pre-built completion files are included in the release archives (`.tar.gz`/`.zip`) on the
[Releases page](https://github.com/sharkdp/fd/releases), in the `autocomplete` directory.
To use these completions:
- **bash**: Source the `fd.bash` file in your `~/.bashrc`, or place it in a directory that gets sourced automatically.
- **zsh**: Move `_fd` to a directory in your `fpath` (e.g., `~/.zfunc`).
- **fish**: Copy `fd.fish` to `~/.config/fish/completions/`.
- **powershell**: Source `_fd.ps1` from one of your [profile scripts](https://learn.microsoft.com/en-us/powershell/scripting/learn/shell/creating-profiles?view=powershell-7.5).
#### Generate from fd
You can also generate completions directly using `fd --gen-completions <shell>`:
If you wish to report a security vulnerability privately, we appreciate your diligence. Please follow the guidelines below to submit your report.
## Reporting
To report a security vulnerability, please provide the following information:
1.**PROJECT**
- Include the URL of the project repository - Example: <https://github.com/sharkdp/fd>
2.**PUBLIC**
- Indicate whether this vulnerability has already been publicly discussed or disclosed.
- If so, provide relevant links.
3.**DESCRIPTION**
- Provide a detailed description of the security vulnerability.
- Include as much information as possible to help us understand and address the issue.
Send this information, along with any additional relevant details, to our [vulnerability reporting form](https://github.com/sharkdp/fd/security/advisories/new).
## Confidentiality
We kindly ask you to keep the report confidential until a public announcement is made.
## Notes
- Vulnerabilities will be handled on a best-effort basis.
- You may request an advance copy of the patched release, but we cannot guarantee early access before the public release.
- You will be notified via email simultaneously with the public announcement.
- We will respond within a few weeks to confirm whether your report has been accepted or rejected.
Thank you for helping to improve the security of our project!
{-F,--fixed-strings}'[treat pattern as literal string instead of a regex]'
+ '(no-require-git)'
"$no(no-ignore-full --no-ignore-vcs --no-require-git)--no-require-git[don't require git repo to respect gitignores]"
+ '(match-full)' # match against full path
{-p,--full-path}'[match the pattern against the full path instead of the basename]'
+ '(follow)' # follow symlinks
{-L,--follow}'[follow symbolic links to directories]'
+ '(abs-path)' # show absolute paths
'(long-listing)'{-a,--absolute-path}'[show absolute paths instead of relative paths]'
+ '(null-sep)' # use null separator for output
'(long-listing)'{-0,--print0}'[separate search results by the null character]'
+ '(long-listing)' # long-listing output
'(abs-path null-sep max-results exec-cmds)'{-l,--list-details}'[use a long listing format with file metadata]'
+ '(max-results)' # max number of results
'(long-listing exec-cmds)--max-results=[limit number of search results to given count and quit]:count'
'(long-listing exec-cmds)-1[limit to a single search result and quit]'
+ '(fs-errors)' # file-system errors
$no'--show-errors[enable the display of filesystem errors]'
+ '(fs-traversal)' # file-system traversal
$no"--one-file-system[don't descend into directories on other file systems]"
'!--mount'
'!--xdev'
+ dir-depth # directory depth
'(--exact-depth -d --max-depth)'{-d+,--max-depth=}'[set max directory depth to descend when searching]:depth'
'!(--exact-depth -d --max-depth)--maxdepth:depth'
'(--exact-depth --min-depth)--min-depth=[set directory depth to descend before start searching]:depth'
'(--exact-depth -d --max-depth --maxdepth --min-depth)--exact-depth=[only search at the exact given directory depth]:depth'
+ prune # pruning
"--prune[don't traverse into matching directories]"
+ filter-misc # filter search
'*'{-t+,--type=}"[filter search by type]:type:(($fd_types))"
'*'{-e+,--extension=}'[filter search by file extension]:extension'
'*'{-E+,--exclude=}'[exclude files/directories that match the given glob pattern]:glob pattern'
'*'{-S+,--size=}'[limit search by file size]:size limit:->size'
'(-o --owner)'{-o+,--owner=}'[filter by owning user and/or group]:owner and/or group:->owner'
+ ignore-file # extra ignore files
'*--ignore-file=[add a custom, low-precedence ignore-file with .gitignore format]: :_files'
+ '(filter-mtime-newer)' # filter by files modified after than
'--changed-within=[limit search to files/directories modified within the given date/duration]:date or duration'
'--changed-after=[alias for --changed-within]:date/duration'
'!--change-newer-than=:date/duration'
'!--newer=:date/duration'
+ '(filter-mtime-older)' # filter by files modified before than
'--changed-before=[limit search to files/directories modified before the given date/duration]:date or duration'
'!--change-older-than=:date/duration'
'!--older=:date/duration'
+ '(color)' # colorize output
{-c+,--color=}'[declare when to colorize search results]:when to colorize:((
auto\:"show colors if the output goes to an interactive console (default)"
never\:"do not use colorized output"
always\:"always use colorized output"
))'
'--hyperlink=-[add hyperlinks to output paths]::when:(auto never always)'
+ '(threads)'
{-j+,--threads=}'[set the number of threads for searching and executing]:number of threads'
+ '(exec-cmds)' # execute command
'(long-listing max-results)'{-x+,--exec=}'[execute command for each search result]:command: _command_names -e:*\;::program arguments: _normal'
'(long-listing max-results)'{-X+,--exec-batch=}'[execute command for all search results at once]:command: _command_names -e:*\;::program arguments: _normal'
'(long-listing max-results)--batch-size=[max number of args for each -X call]:size'
+ other
'!(--max-buffer-time)--max-buffer-time=[set amount of time to buffer before showing output]:time (ms)'
+ '(about)' # about flags
'(: * -)'{-h,--help}'[display help message]'
'(: * -)'{-V,--version}'[display version information]'
+ path-sep # set path separator for output
$no'(--path-separator)--path-separator=[set the path separator to use when printing file paths]:path separator'
+ search-path
$no'(--base-directory)--base-directory=[change the current working directory to the given path]:directory:_files -/'
$no'(*)*--search-path=[set search path (instead of positional <path> arguments)]:directory:_files -/'
+ strip-cwd-prefix
$no'(strip-cwd-prefix exec-cmds)--strip-cwd-prefix=-[When to strip ./]::when:(always never auto)'
+ and
'--and=[additional required search path]:pattern'
+ args # positional arguments
'1: :_guard "^-*" pattern'
'(--search-path)*:directory:_files -/'
)
# Strip out argument groups where unsupported (see above)
is a simple, fast and user-friendly alternative to
.BRfind(1).
.P
By default
.Bfd
uses regular expressions for the pattern. However, this can be changed to use simple glob patterns
with the '\-\-glob' option.
.P
By default
.Bfd
will exclude hidden files and directories, as well as any files that match gitignore rules
or ignore rules in .ignore or .fdignore files.
.P
If you wish to search all files in a specific directory, you can use '' or . as the search pattern,
to match all files. Or you can use the '\-\-search\-path' option to specify the path(s) instead of
the positional parameter.
.P
Options may be given anywhere on the command line.
.SHOPTIONS
.TP
.B\-H,\-\-hidden
Include hidden files and directories in the search results
(default: hidden files and directories are skipped). The flag can be overridden with '--no-hidden'.
.IP
Ignored files are still excluded unless \-\-no\-ignore or \-\-no\-ignore\-vcs
is also used.
.TP
.B\-I,\-\-no\-ignore
Show search results from files and directories that would otherwise be ignored by
.RS
.IP\[bu]2
.I.gitignore
.IP\[bu]
.I.git/info/exclude
.IP\[bu]
The global gitignore configuration (by default
.IR$HOME/.config/git/ignore)
.IP\[bu]
.I.ignore
.IP\[bu]
.I.fdignore
.IP\[bu]
The global fd ignore file (usually
.I$HOME/.config/fd/ignore
)
.RE
.IP
The flag can be overridden with '--ignore'.
.TP
.B\-u,\-\-unrestricted
Perform an unrestricted search, including ignored and hidden files. This is an alias for '--hidden --no-ignore'.
.TP
.B\-\-no\-ignore\-vcs
Show search results from files and directories that would otherwise be ignored by gitignore files
including
.IR.gitignore,
.IR.git/info/exclude,
and the global gitignore configuration
.RI(core.excludesFile
git setting, which defaults to
.IR$HOME/.config/git/ignore).
The flag can be overridden with '--ignore-vcs'.
.TP
.B\-\-no\-require\-git
Do not require a git repository to respect gitignores. By default, fd will only
respect global gitignore rules, .gitignore rules and local exclude rules if fd
detects that you are searching inside a git repository. This flag allows you to
relax this restriction such that fd will respect all git related ignore rules
regardless of whether you’re searching in a git repository or not. The flag can
be overridden with '--require-git'.
.TP
.B\-\-no\-ignore\-parent
Show search results from files and directories that would otherwise be ignored by gitignore files in
parent directories.
.TP
.B\-s,\-\-case\-sensitive
Perform a case-sensitive search. By default, fd uses case-insensitive searches, unless the
pattern contains an uppercase character (smart case).
.TP
.B\-i,\-\-ignore\-case
Perform a case-insensitive search. By default, fd uses case-insensitive searches, unless the
pattern contains an uppercase character (smart case).
.TP
.B\-g,\-\-glob
Perform a glob-based search instead of a regular expression search.
If combined with the '\-\-full-path' option, '**' can be used to match multiple path components.
.TP
.B\-\-regex
Perform a regular-expression based search (default). This can be used to override --glob.
.TP
.B\-F,\-\-fixed\-strings
Treat the pattern as a literal string instead of a regular expression. Note that this also
performs substring comparison. If you want to match on an exact filename, consider using '\-\-glob'
or '\-\-exact'.
.TP
.B\-\-exact
Perform an exact match. This is equivalent to '\-\-fixed\-strings' but requires the pattern to
match the entire filename (or the full path if '\-\-full\-path' is used), rather than a substring.
Special regex characters in the pattern are treated as literal characters.
Cannot be used together with '\-\-glob' or '\-\-fixed\-strings'.
.TP
.BI"\-\-and "pattern
Add additional required search patterns, all of which must be matched. Multiple additional
patterns can be specified. The patterns are regular expressions, unless '\-\-glob'
or '\-\-fixed\-strings' is used.
.TP
.B\-a,\-\-absolute\-path
Shows the full path starting from the root as opposed to relative paths.
The flag can be overridden with '--relative-path'.
.TP
.B\-l,\-\-list\-details
Use a detailed listing format like 'ls -l'. This is basically an alias
for '--exec-batch ls -l' with some additional 'ls' options. This can be used
to see more metadata, to show symlink targets and to achieve a deterministic
sort order.
.TP
.B\-L,\-\-follow
By default, fd does not descend into symlinked directories. Using this flag, symbolic links are
also traversed. The flag can be overridden with '--no-follow'.
.TP
.B\-p,\-\-full\-path
By default, the search pattern is only matched against the filename (or directory name). Using
this flag, the
.Ipattern
is matched against the full path.
.TP
.B\-0,\-\-print0
Separate search results by the null character (instead of newlines). Useful for piping results to
.IRxargs.
.TP
.B\-\-max\-resultscount
Limit the number of search results to 'count' and quit immediately.
.TP
.B\-1
Limit the search to a single result and quit immediately. This is an alias for '--max-results=1'.
.TP
.B\-q,\-\-quiet
When the flag is present, the program does not print anything and will instead exit with a code of 0 if there is at least one search result.
Otherwise, the exit code will be 1.
This is mainly for usage in scripts and can be faster than checking for output because the search can be stopped early after the first match.
.B\-\-has\-results
can be used as an alias.
.TP
.B\-\-show-errors
Enable the display of filesystem errors for situations such as insufficient
permissions or dead symlinks.
.TP
.B\-\-strip-cwd-prefix[when]
By default, relative paths are prefixed with './' when -x/--exec,
-X/--exec-batch, or -0/--print0 are given, to reduce the risk of a
path starting with '-' being treated as a command line option. Use
this flag to change this behavior. If this flag is used without a value,
it is equivalent to passing "always". Possible values are:
.RS
.IPnever
Never strip the ./ at the beginning of paths
.IPalways
Always strip the ./ at the beginning of paths
.IPauto
Only strip if used with --exec, --exec-batch, or --print0. That is, it resets to the default behavior.
.RE
.TP
.B\-\-one\-file\-system,\-\-mount,\-\-xdev
By default, fd will traverse the file system tree as far as other options dictate. With this flag, fd ensures that it does not descend into a different file system than the one it started in. Comparable to the -mount or -xdev filters of find(1).
.TP
.B\-h,\-\-help
Print help information.
.TP
.B\-V,\-\-version
Print version information.
.TP
.BI"\-d, \-\-max\-depth "d
Limit directory traversal to at most
.Id
levels of depth. By default, there is no limit on the search depth.
.TP
.BI"\-\-min\-depth "d
Only show search results starting at the given depth. See also: '--max-depth' and '--exact-depth'.
.TP
.BI"\-\-exact\-depth "d
Only show search results at the exact given depth. This is an alias for '--min-depth <depth> --max-depth <depth>'.
.TP
.B\-\-prune
Do not traverse into matching directories.
.TP
.BI"\-t, \-\-type "filetype
Filter search by type:
.RS
.IP"f, file"
regular files
.IP"d, dir, directory"
directories
.IP"l, symlink"
symbolic links
.IP"b, block-device"
block devices
.IP"c, char-device"
character devices
.IP"s, socket"
sockets
.IP"p, pipe"
named pipes (FIFOs)
.IP"x, executable"
executable (files)
.IP"e, empty"
empty files or directories
.RE
.RS
This option can be specified more than once to include multiple file types.
Searching for '--type file --type symlink' will show both regular files as well as
symlinks. Note that the 'executable' and 'empty' filters work differently: '--type
executable' implies '--type file' by default. And '--type empty' searches for
empty files and directories, unless either '--type file' or '--type directory' is
specified in addition.
Examples:
- Only search for files:
fd --type file …
fd -tf …
- Find both files and symlinks
fd --type file --type symlink …
fd -tf -tl …
- Find executable files:
fd --type executable
fd -tx
- Find empty files:
fd --type empty --type file
fd -te -tf
- Find empty directories:
fd --type empty --type directory
fd -te -td
.RE
.TP
.BI"\-e, \-\-extension "ext
Filter search results by extension
.IRext.
This option can be used repeatedly to allow for multiple possible extensions.
By default, extension filters apply to both files and directories. Use
\fB\-\-type\fR to restrict the search to specific types.
If you want to search for files without extension, you can use the regex '^[^.]+$'
as a normal search pattern.
.TP
.BI"\-E, \-\-exclude "glob
Exclude files/directories that match the given glob pattern.
This overrides any other ignore logic.
Multiple exclude patterns can be specified.
Examples:
\-\-exclude '*.pyc'
\-\-exclude node_modules
.TP
.BI"\-\-ignore-contain "name
Exclude directories that (directly) contain the given name.
This option can be specified multiple times.
.TP
.BI"\-\-ignore-file "path
Add a custom ignore-file in '.gitignore' format.
These files have a low precedence.
.TP
.BI"\-c, \-\-color "when
Declare
.Iwhen
to colorize search results:
.RS
.IPauto
Colorize output when standard output is connected to terminal (default).
.IPnever
Do not colorize output.
.IPalways
Always colorize output.
.RE
.TP
.B"\-\-hyperlink
Specify whether the output should use terminal escape codes to indicate a hyperlink to a
file url pointing to the path.
The value can be auto, always, or never.
Currently, the default is "never", and if the option is used without an argument "auto" is
used. In the future this may be changed to "auto" and "always".
.RS
.IPauto
Only output hyperlinks if color is also enabled, as a proxy for whether terminal escape
codes are acceptable.
.IPnever
Never output hyperlink escapes.
.IPalways
Always output hyperlink escapes, regardless of color settings.
.RE
.TP
.BI"\-j, \-\-threads "num
Set number of threads to use for searching & executing (default: number of available CPU cores).
.TP
.BI"\-S, \-\-size "size
Limit results based on the size of files using the format
.I<+-><NUM><UNIT>
.RS
.IP'+'
file size must be greater than or equal to this
.IP'-'
file size must be less than or equal to this
.P
If neither '+' nor '-' is specified, file size must be exactly equal to this.
.IP'NUM'
The numeric size (e.g. 500)
.IP'UNIT'
The units for NUM. They are not case-sensitive.
Allowed unit values:
.RS
.IP'b'
bytes
.IP'k'
kilobytes (base ten, 10^3 = 1000 bytes)
.IP'm'
megabytes
.IP'g'
gigabytes
.IP't'
terabytes
.IP'ki'
kibibytes (base two, 2^10 = 1024 bytes)
.IP'mi'
mebibytes
.IP'gi'
gibibytes
.IP'ti'
tebibytes
.RE
.RE
.TP
.BI"\-\-changed-within "date|duration
Filter results based on the file modification time.
Files with modification timestamps greater than the argument will be returned.
The argument can be provided as a duration (\fI10h, 1d, 35min\fR) or as a specific point
in time as full RFC3339 format with time zone, as a date or datetime in the
local time zone (\fIYYYY-MM-DD\fR or \fIYYYY-MM-DD HH:MM:SS\fR), or as the prefix '@'
followed by the number of seconds since the Unix epoch (@[0-9]+).
\fB\-\-change-newer-than\fR,
.B--newer
or
.B--changed-after
can be used as aliases.
Examples:
\-\-changed-within 2weeks
\-\-change-newer-than "2018-10-27 10:00:00"
\-\-newer 2018-10-27
\-\-changed-after @1704067200
.TP
.BI"\-\-changed-before "date|duration
Filter results based on the file modification time.
Files with modification timestamps less than the argument will be returned.
The argument can be provided as a duration (\fI10h, 1d, 35min\fR) or as a specific point
in time as full RFC3339 format with time zone, as a date or datetime in the
local time zone (\fIYYYY-MM-DD\fR or \fIYYYY-MM-DD HH:MM:SS\fR), or as the prefix '@'
followed by the number of seconds since the Unix epoch (@[0-9]+).
.B--change-older-than
or
.B--older
can be used as aliases.
Examples:
\-\-changed-before "2018-10-27 10:00:00"
\-\-change-older-than 2weeks
\-\-older @1704067200
.TP
.BI"-o, \-\-owner "[user][:group]
Filter files by their user and/or group. Format: [(user|uid)][:(group|gid)]. Either side
is optional. Precede either side with a '!' to exclude files instead.
Examples:
\-\-owner john
\-\-owner :students
\-\-owner "!john:students"
.TP
.BI"-C, \-\-base\-directory "path
Change the current working directory of fd to the provided path. This means that search results will
be shown with respect to the given base path. Note that relative paths which are passed to fd via the
positional \fIpath\fR argument or the \fB\-\-search\-path\fR option will also be resolved relative to
this directory.
.TP
.BI"\-\-path\-separator "separator
Set the path separator to use when printing file paths. The default is the OS-specific separator
('/' on Unix, '\\' on Windows).
.TP
.BI"\-\-search\-path "search\-path
Provide paths to search as an alternative to the positional \fIpath\fR argument. Changes the usage to
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:29.7126px;line-height:0;font-family:'Fira Sans Condensed';-inkscape-font-specification:'Fira Sans Condensed, ';white-space:pre;inline-size:37.3715;fill:#e5e5e5;fill-opacity:1;stroke-width:0.742816"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:29.7126px;line-height:0;font-family:'Fira Sans Condensed';-inkscape-font-specification:'Fira Sans Condensed, ';white-space:pre;inline-size:37.3715;fill:#00ccff;fill-opacity:0.996078;stroke-width:0.742816"
d="m 42.164961,159.42939 -1.554274,-1.89462 -1.975227,-0.005 c -0.941841,0.014 -1.165466,0.27232 -1.14085,2.88812 z"
id="path40006"
sodipodi:nodetypes="ccccc"/>
<rect
style="fill:#01ccff;fill-opacity:1;stroke:none;stroke-width:2.3;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0.80126;paint-order:stroke fill markers"
d="m 42.164961,159.42939 -1.554274,-1.89462 -1.975227,-0.005 c -0.941841,0.014 -1.165466,0.27232 -1.14085,2.88812 z"
id="path41947"
sodipodi:nodetypes="ccccc"/>
<rect
style="fill:#535d6c;fill-opacity:0.993797;stroke:none;stroke-width:2.3;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0.80126;paint-order:stroke fill markers"
d="m 42.164961,159.42939 -1.554274,-1.89462 -1.975227,-0.005 c -0.941841,0.014 -1.165466,0.27232 -1.14085,2.88812 z"
id="path41953"
sodipodi:nodetypes="ccccc"/>
<rect
style="fill:#535d6c;fill-opacity:0.993797;stroke:none;stroke-width:2.3;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0.80126;paint-order:stroke fill markers"
about = "A program to find entries in your filesystem with regex and glob based matching. By default, fd respects gitignore rules, ignores hidden directories, and is case insensitive.",
after_long_help = "Bugs can be reported on GitHub: https://github.com/sharkdp/fd/issues",
/// By default, the search pattern is only matched against the filename (or directory name). Using this flag, the pattern is matched against the full (absolute) path. Example:
/// fd --glob -p '**/.git/config'
#[arg(
long,
short = 'p',
help = "Search full abs. path (default: filename only)",
long_help,
verbatim_doc_comment
)]
pubfull_path: bool,
/// Separate search results by the null character (instead of newlines).
/// Useful for piping results to 'xargs'.
#[arg(
long = "print0",
short = '0',
conflicts_with("list_details"),
hide_short_help = true,
help = "Separate search results by the null character",
long_help
)]
pubnull_separator: bool,
/// Limit the directory traversal to a given depth. By default, there is no
/// limit on the search depth.
#[arg(
long,
short = 'd',
value_name = "depth",
alias("maxdepth"),
help = "Set maximum search depth (default: none)",
long_help
)]
max_depth: Option<usize>,
/// Only show search results starting at the given depth.
/// See also: '--max-depth' and '--exact-depth'
#[arg(
long,
value_name = "depth",
hide_short_help = true,
alias("mindepth"),
help = "Only show search results starting at the given depth.",
long_help
)]
min_depth: Option<usize>,
/// Only show search results at the exact given depth. This is an alias for
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Thayne McCombs
