Ignore handling

Active contributors: sharkdp, tmccombs, tavianator

Purpose

This page is the user-facing companion to systems/ignore-rules. It walks through the complete defaults that apply when fd starts a search, then explains every flag and ignore source that can change those defaults.

The defaults

Without any flags, fd:

1. Skips entries whose name starts with . (hidden files and directories).
2. Honours .gitignore files in the current and parent directories — but only inside a git repository (i.e., when .git/ exists somewhere in the ancestor chain).
3. Honours .ignore files in the same locations.
4. Honours .fdignore files in the same locations.
5. Honours the global ignore file at ${etcetera::config_dir()}/fd/ignore.
6. Honours --exclude glob patterns from the command line, applied as OverrideBuilder rules.
7. Does not honour parent-directory ignore files when the user disables both read_fdignore and read_vcsignore.
8. Stops descending into subtrees whose root contains a name listed in --ignore-contain.

Flag → behaviour matrix

Flag	What changes
-H, --hidden	Show dotfiles (ignore_hidden = false).
--no-hidden	Override; reset to the default.
-I, --no-ignore	Disable all ignore-file mechanisms (gitignore, .ignore, .fdignore, global, parent). Hidden files still hidden.
--ignore	Override; reset to the default.
-u, --unrestricted	Counted alias for --no-ignore --hidden. -uu works because rg_alias_hidden_ignore is a u8 counter, but the second u is just for muscle memory.
--no-ignore-vcs	Disable only gitignore handling. Other ignore files are still honoured.
--ignore-vcs	Override.
--no-ignore-parent	Stop walking up to ancestor directories looking for ignore files.
--ignore-parent	Override (added in Unreleased, PR #1958).
--no-global-ignore-file	Skip the global fdignore.
--no-require-git	Honour gitignore rules even outside git repositories. By default, fd only respects git rules when .git/ exists.
--require-git	Override.
--ignore-file PATH	Append a custom ignore file. May be repeated.
-E, --exclude GLOB	Add an inline exclude pattern. May be repeated.
--ignore-contain NAME	Skip directories that contain a child entry called NAME (e.g. CACHEDIR.TAG).

The Boolean simplification of these flags is in construct_config (src/main.rs):

ignore_hidden: !(opts.hidden || opts.rg_alias_ignore()),
read_fdignore: !(opts.no_ignore || opts.rg_alias_ignore()),
read_vcsignore: !(opts.no_ignore || opts.rg_alias_ignore() || opts.no_ignore_vcs),
require_git_to_read_vcsignore: !opts.no_require_git,
read_parent_ignore: !opts.no_ignore_parent,
read_global_ignore: !(opts.no_ignore || opts.rg_alias_ignore() || opts.no_global_ignore_file),

Ignore file syntax

Every ignore file format that fd understands shares .gitignore syntax:

• Comments start with #.
• Each line is a glob pattern relative to the file's location.
• Trailing / matches directories only.
• Leading / anchors to the file's directory.
• ** matches any number of path components.
• A leading ! re-includes a previously excluded entry.

This is implemented by the ignore crate; fd does not parse them itself.

Common recipes

# See absolutely everything (hidden + ignored):
fd -uu

# Find all files in a build directory that gitignore would normally hide:
fd --no-ignore-vcs -tf '\.tmp$' build/

# Permanently exclude a noisy mountpoint via ~/.config/fd/ignore:
echo '/mnt/external-drive' >> ~/.config/fd/ignore

# Skip everything that lives under a CACHEDIR.TAG-marked directory:
fd --ignore-contain CACHEDIR.TAG

# Project-local exclusion: drop a .fdignore at the repo root:
echo 'target/' > .fdignore

How --exclude differs from .fdignore

--exclude PATTERN is implemented via ignore::overrides::OverrideBuilder (see WorkerState::build_overrides in src/walk.rs). Override rules take priority over every ignore file, which means --exclude '*.bak' excludes those files even if a .fdignore re-includes them with !*.bak. In contrast, .fdignore and other ignore files compose with normal precedence (deeper rules override shallower ones).

The .git-directory caveat

Before 9.0.0, fd never automatically ignored .git/. 9.0.0 added a special case: when --hidden was used together with VCS-ignore handling, .git directories were silently skipped. This broke a number of workflows and was reverted in 10.0.0. The current behaviour is: .git is hidden by default like any other dotfile, and -H shows it like any other dotfile. To get the 9.0.0 behaviour back, add .git/ to the global fdignore file:

echo '.git/' >> ~/.config/fd/ignore

Diagnostics

• Pattern only matches dotfiles. ensure_use_hidden_option_for_leading_dot_pattern (src/main.rs) detects when the pattern is anchored with ^\. and --hidden was not passed; it suggests adding -H.
• Malformed exclude pattern. WorkerState::build_overrides returns anyhow!("Malformed exclude pattern: {}", e).
• Malformed ignore file. print_error("Malformed pattern in custom ignore file. {err}") is emitted unless the error is ignore::Error::Partial, which is tolerated.

Related pages

• Walker — owns build_walker and the override builder.
• Ignore rules — the implementation-side companion.
• Lore — context for the 9.0/10.0 .git flip-flop.