BFS(1)

📦
version 4.1.5 · 11 versions
, in arch rolling

🌸 NAME 🌸

bfs — breadth-first search for your files

okay so this is the bfs(1) page from the General Commands Manual, bestie. It's literally find(1)'s breadth-first bestie, and it's iconic.

✨ SYNOPSIS ✨

The whole command-line vibe is:

bfs [flags...]  [paths...]  [expression...]

flags (-H/-L/-P etc.), paths, and expressions may be freely mixed in any order. no cap, mix them however you want.

🦋 DESCRIPTION 🦋

bfs is the breadth-first version of the UNIX find(1) command.

It supports almost every feature from every major find(1) implementation, so your existing command lines should work as-is. It also adds some features of its own, such as a more forgiving command line parser and some additional options. slay.

Each path specified on the command line is treated as a starting path to search through. If no paths are specified, the current directory (.) is searched by default.

Like find(1), bfs interprets its arguments as a short-circuiting Boolean expression. For example,

bfs \( -name '*.txt' -or -lname '*.txt' \) -and -print

will print all the paths that are either .txt files or symbolic links to .txt files. -and is implied between two consecutive expressions, so this is equivalent:

bfs \( -name '*.txt' -or -lname '*.txt' \) -print

Finally, -print is implied if no actions are specified, so this too is equivalent:

bfs -name '*.txt' -or -lname '*.txt'

Most options that take a numeric argument N will also accept -N or +N. -N means "less than N," and +N means "greater than N." periodt.

💅 FLAGS 💅

These are the little command-line flags that set the whole search vibe:

  • -H — follow symbolic links on the command line, but not while searching.
  • -L — follow all symbolic links.
  • -P — never follow symbolic links (the default).
  • -E — use extended regular expressions (same as -regextype posix-extended).
  • -X — filter out files with non-xargs(1)-safe names.
  • -d — search in post-order (same as -depth).
  • -s — visit directory entries in sorted order. The sorting takes place within each directory separately, which makes it different from bfs ... | sort, but still provides a deterministic ordering.
  • -x — don't descend into other mount points (same as -xdev).
  • -f PATH — treat PATH as a path to search (useful if it begins with a dash).
  • -D FLAG — turn on a debugging flag (see -D help).
  • -ON — enable optimization level N (default: 3).
    • -O0 — disable all optimizations.
    • -O1 — basic logical simplifications.
    • -O2 — all -O1 optimizations, plus dead code elimination and data flow analysis.
    • -O3 — all -O2 optimizations, plus re-order expressions to reduce expected cost.
    • -O4/-Ofast — all optimizations, including aggressive optimizations that may alter the observed behavior in corner cases.
  • -S bfs|dfs|ids|eds — choose the search strategy.
    • bfs — breadth-first search (the default).
    • dfs — depth-first search. Uses less memory than breadth-first search, but is typically slower to return relevant results.
    • ids — iterative deepening search. Performs repeated depth-first searches with increasing depth limits. This gives results in the same order as breadth-first search, but with the reduced memory consumption of depth-first search. Tends to be very slow in practice, so use it only if you absolutely need breadth-first ordering, but -S bfs consumes too much memory.
    • eds — exponential deepening search. A compromise between breadth- and depth-first search, which searches exponentially increasing depth ranges (e.g. 0-1, 1-2, 2-4, 4-8, etc.). Provides many of the benefits of breadth-first search with depth-first's reduced memory consumption. Typically far faster than -S ids.
  • -jN — search with N threads in parallel (default: number of CPUs, up to 8).

🎀 OPERATORS 🎀

Boolean expression time, bestie. This is the main character energy of the whole thing:

  • ( expression ) — parentheses are used for grouping expressions together. You'll probably have to write \( expression \) to avoid the parentheses being interpreted by the shell.
  • ! expression, -not expression — the "not" operator: returns the negation of the truth value of the expression. You may have to write \! expression to avoid ! being interpreted by the shell.
  • expression expression, expression -a expression, expression -and expression — short-circuiting "and" operator: if the left-hand expression is true, returns the right-hand expression; otherwise, returns false.
  • expression -o expression, expression -or expression — short-circuiting "or" operator: if the left-hand expression is false, returns the right-hand expression; otherwise, returns true.
  • expression , expression — the "comma" operator: evaluates the left-hand expression but discards the result, returning the right-hand expression.

🌈 SPECIAL FORMS 🌈

  • -exclude expression — exclude all paths matching the expression from the search. This is more powerful than -prune, because it applies even when the expression wouldn't otherwise be evaluated, due to -depth or -mindepth for example. Exclusions are always applied before other expressions, so it may be least confusing to put them first on the command line.
  • -help, --help — print usage information, and exit immediately (without parsing the rest of the command line or processing any files).
  • -version, --version — print version information, and exit immediately.

🍓 OPTIONS 🍓

More options, because of course there are. Obsessed.

  • -color, -nocolor — turn colors on or off (default: -color if outputting to a terminal, -nocolor otherwise).
  • -daystart — measure time relative to the start of today.
  • -depth — search in post-order (descendents first).
  • -follow — follow all symbolic links (same as -L).
  • -files0-from FILE — treat the NUL ('\0')-separated paths in FILE as starting points for the search. Pass -files0-from - to read the paths from standard input.
  • -ignore_readdir_race, -noignore_readdir_race — whether to report an error if bfs detects that the file tree is modified during the search (default: -noignore_readdir_race).
  • -maxdepth N, -mindepth N — ignore files deeper/shallower than N.
  • -mount — exclude mount points entirely from the results.
  • -noerror — ignore any errors that occur during traversal.
  • -nohidden — exclude hidden files and directories.
  • -noleaf — ignored; for compatibility with GNU find.
  • -regextype TYPE — use TYPE-flavored regular expressions. The possible types are:
    • posix-basic — POSIX basic regular expressions (the default).
    • posix-extended — POSIX extended regular expressions.
    • ed — like ed(1) (same as posix-basic).
    • emacs — like emacs(1).
    • grep — like grep(1).
    • sed — like sed(1) (same as posix-basic).

See regex(7) for a description of regular expression syntax.

  • -status — display a status bar while searching.
  • -unique — skip any files that have already been seen. Particularly useful along with -L.
  • -warn, -nowarn — turn on or off warnings about the command line.
  • -xdev — don't descend into other mount points. Unlike -mount, the mount point itself is still included.

💅 TESTS 💅

okay bestie, these are the test filters — the vibe check every file has to pass. 💖

  • -acl — matches files with a non-trivial Access Control List (acl(5)).
  • -amin [-+]N — matches files accessed N minutes ago.
  • -Bmin [-+]N — matches files Birthed N minutes ago.
  • -cmin [-+]N — matches files changed N minutes ago.
  • -mmin [-+]N — matches files modified N minutes ago.
  • -anewer FILE — matches files accessed more recently than FILE was modified.
  • -Bnewer FILE — matches files Birthed more recently than FILE was modified.
  • -cnewer FILE — matches files changed more recently than FILE was modified.
  • -mnewer FILE — matches files modified more recently than FILE was modified.
  • -asince TIME — matches files accessed more recently than the ISO 8601-style timestamp TIME. Peep -newerXY for examples of the timestamp format.
  • -Bsince TIME — matches files Birthed more recently than the ISO 8601-style timestamp TIME. Peep -newerXY for examples of the timestamp format.
  • -csince TIME — matches files changed more recently than the ISO 8601-style timestamp TIME. Peep -newerXY for examples of the timestamp format.
  • -msince TIME — matches files modified more recently than the ISO 8601-style timestamp TIME. Peep -newerXY for examples of the timestamp format.
  • -atime [-+]N — matches files accessed N days ago.
  • -Btime [-+]N — matches files Birthed N days ago.
  • -ctime [-+]N — matches files changed N days ago.
  • -mtime [-+]N — matches files modified N days ago.
  • -capable — matches files with POSIX.1e capabilities(7) set.
  • -context GLOB — matches files whose SELinux context matches the GLOB.
  • -depth [-+]N — matches files with depth N.
  • -empty — matches empty files/directories.
  • -executable — matches files the current user can execute.
  • -readable — matches files the current user can read.
  • -writable — matches files the current user can write.
  • -false — always false.
  • -true — always true.
  • -flags [-+]FLAGS — matches files with matching inode FLAGS.
  • -fstype TYPE — matches files on file systems with the given TYPE.
  • -gid [-+]N — matches files owned by group ID N.
  • -uid [-+]N — matches files owned by user ID N.
  • -group NAME — matches files owned by the group NAME.
  • -user NAME — matches files owned by the user NAME.
  • -hidden — matches hidden files (those beginning with .).
  • -ilname GLOB — case-insensitive version of -lname.
  • -iname GLOB — case-insensitive version of -name.
  • -ipath GLOB — case-insensitive version of -path.
  • -iregex REGEX — case-insensitive version of -regex.
  • -iwholename GLOB — case-insensitive version of -wholename.
  • -inum [-+]N — matches files with inode number N.
  • -links [-+]N — matches files with N hard links.
  • -lname GLOB — matches symbolic links whose target matches the GLOB.
  • -name GLOB — matches files whose name matches the GLOB.
  • -newer FILE — matches files newer than FILE.
  • -newerXY REFERENCE — matches files whose X time is newer than the Y time of REFERENCE. X and Y can be any of [aBcm] (access/Birth/change/modification). Y may also be t to parse REFERENCE as an ISO 8601-style timestamp. For example:
    • 1991-12-14
    • 1991-12-14T03:00
    • 1991-12-14T03:00-07:00
    • '1991-12-14 10:00Z'
  • -nogroup — matches files owned by nonexistent groups.
  • -nouser — matches files owned by nonexistent users.
  • -path GLOB — matches files whose entire path matches the GLOB.
  • -wholename GLOB — matches files whose entire path matches the GLOB.
  • -perm [-+/]MODE — matches files with a matching mode.
  • -regex REGEX — matches files whose entire path matches the regular expression REGEX.
  • -samefile FILE — matches hard links to FILE.
  • -since TIME — matches files modified since the ISO 8601-style timestamp TIME. Peep -newerXY for examples of the timestamp format.
  • -size [-+]N[cwbkMGTP] — matches files with the given size. The unit can be one of
    • chars (1 byte)
    • words (2 bytes)
    • blocks (512 bytes, the default)
    • kiB (1024 bytes)
    • MiB (1024 kiB)
    • GiB (1024 MiB)
    • TiB (1024 GiB)
    • PiB (1024 TiB)
  • -sparse — matches files that occupy fewer disk blocks than expected.
  • -type [bcdlpfswD] — matches files of the given type. The possible types are
    • block device
    • character device
    • directory
    • link (symbolic)
    • pipe
    • file (regular)
    • socket
    • whiteout
    • Door

Multiple types can be given at once, separated by commas. For example, -type d,f matches both directories and regular files.

  • -used [-+]N — matches files last accessed N days after they were changed.
  • -xattr — matches files with extended attributes (xattr(7)).
  • -xattrname NAME — matches files with the extended attribute NAME.
  • -xtype [bcdlpfswD] — matches files of the given type, following links when -type would not, and vice versa.

🎬 ACTIONS 🎬

these are the do-something options, bestie. like, they actually act on the files. 💅

  • -delete — deletes any found files (implies -depth). 🚨
  • -rm — deletes any found files (implies -depth). 🚨
  • -exec command ... {} ; — executes a command.
  • -exec command ... {} + — executes a command with multiple files at once.
  • -ok command ... {} ; — prompts the user whether to execute a command.
  • -execdir command ... {} ; — like -exec/-ok, but runs the command in the same directory as the found file(s).
  • -execdir command ... {} + — like -exec/-ok, but runs the command in the same directory as the found file(s).
  • -okdir command ... {} ; — like -exec/-ok, but runs the command in the same directory as the found file(s).
  • -exit [STATUS] — exits immediately with the given status (0 if unspecified).
  • -fls FILE — like -ls, but writes to FILE instead of standard output.
  • -fprint FILE — like -print, but writes to FILE instead of standard output.
  • -fprint0 FILE — like -print0, but writes to FILE instead of standard output.
  • -fprintf FILE FORMAT — like -printf, but writes to FILE instead of standard output.
  • -limit N — quits once this action is evaluated N times.
  • -ls — lists files like ls -dils.
  • -print — prints the path to the found file.
  • -print0 — like -print, but uses the null character ('\0') as a separator rather than newlines. Useful in conjunction with xargs -0.
  • -printf FORMAT — prints according to a format string (see find(1)). These additional format directives are supported:
    • %w — the file's birth time, in the same format as %a/%c/%t.
    • %Wk — field k of the file's birth time, in the same format as %Ak/%Ck/%Tk.
  • -printx — like -print, but escapes whitespace and quotation characters, to make the output safe for xargs(1). Consider using -print0 and xargs -0 instead.
  • -prune — doesn't descend into this directory. This has no effect if -depth is enabled (either explicitly, or implicitly by -delete). Use -exclude instead in that case.
  • -quit — quits immediately.

🌱 ENVIRONMENT 🌱

certain environment variables affect the behavior of bfs. yes, bestie, the environment is literally part of the plot. 🌈

  • LANG, LC_* — specifies the locale(7) in use for various things. bfs is not (yet) translated to any languages except English, but the locale will still affect the format of printed values. Yes/no prompts (e.g. from -ok) will also be interpreted according to the current locale.
  • LS_COLORS, BFS_COLORS — controls the colors used when displaying file paths if -color is enabled. bfs interprets LS_COLORS the same way GNU ls(1) does (see dir_colors(5)). BFS_COLORS can be used to customize bfs without affecting other commands.
  • NO_COLOR — causes bfs to default to -nocolor if it is set (see https://no-color.org/).
  • PAGER — specifies the pager used for -help output. Defaults to less(1), if found on the current PATH, otherwise more(1).
  • PATH — used to resolve executables for -exec[dir] and -ok[dir].
  • POSIXLY_CORRECT — makes bfs conform more strictly to the POSIX.1-2017 specification for find(1). Currently this has two effects:
    • Disables warnings by default, because POSIX prohibits writing to standard error (except for the -ok prompt), unless the command also fails with a non-zero exit status.
    • Makes -ls and -fls use 512-byte blocks instead of 1024-byte blocks. (POSIX does not specify these actions, but BSD find(1) implementations use 512-byte blocks, while GNU find(1) uses 1024-byte blocks by default.)

It does not disable bfs's various extensions to the base POSIX functionality. POSIXLY_CORRECT has the same effects on GNU find(1).

🌸 EXAMPLES 🌸

okay, real talk: examples are the main character. here are the exact ones, no cap. 💅

  • bfs — with no arguments, bfs prints all files under the current directory in breadth-first order.
  • bfs -name '*.txt' — prints all the .txt files under the current directory. *.txt is quoted to ensure the glob is processed by bfs rather than the shell.
  • bfs -name access_log -L /var — finds all files named access_log under /var, following symbolic links. bfs allows flags and paths to appear anywhere on the command line.
  • bfs ~ -not -user $USER — prints all files in your home directory not owned by you.
  • bfs -xtype l — finds broken symbolic links.
  • bfs -name config -exclude -name .git — finds all files named config, skipping every .git directory.
  • bfs -type f -executable -exec strip {} + — runs strip(1) on all executable files it finds, passing it multiple files at a time.

💀 BUGS 💀

found a bug? spill: https://github.com/tavianator/bfs/issues

👑 AUTHOR 👑

🔎 SEE ALSO 🔎

💖 mwah 💋 — that's the wrap, bestie! source/version bfs 4.1.5, date 2026-10-28, manual BFS(1). periodt, go be iconic. 🫶

📦 where this page comes from