--- name: "bfs" section: "1" platform: "linux" package: "bfs" version: "4.1.4-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/bfs" --- # bfs(1) breadth-first search for your files ## NAME bfs - breadth-first search for your files ## SYNOPSIS **bfs** \[**flags**...\] \[*paths*...\] \[**expression**...\] flags (**-H**/**-L**/**-P** etc.), *paths*, and **expressions** may be freely mixed in any order. ## DESCRIPTION **bfs** is a breadth-first version of the UNIX [**find**(1)](/find/1.md) command. **bfs** supports almost every feature from every major [**find**(1)](/find/1.md) 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. 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)](/find/1.md), **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*." ## FLAGS - **-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)](/xargs/1.md)-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*). **-O***N* Enable optimization level *N* (default: *3*). - **-O***0* Disable all optimizations. - **-O***1* Basic logical simplifications. - **-O***2* All **-O***1* optimizations, plus dead code elimination and data flow analysis. - **-O***3* All **-O***2* optimizations, plus re-order expressions to reduce expected cost. - **-O***4*/**-O***fast* 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*. - **-j***N* Search with *N* threads in parallel (default: number of CPUs, up to *8*). ## OPERATORS - **(** *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 - **-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)](/ed/1.md) (same as *posix-basic*). - *emacs* Like [**emacs**(1)](/emacs/1.md). - *grep* Like [**grep**(1)](/grep/1.md). - *sed* Like [**sed**(1)](/sed/1.md) (same as *posix-basic*). See [**regex**(7)](/regex/7.md) 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 - **-acl** Find files with a non-trivial Access Control List ([**acl**(5)](/acl/5.md)). **-amin** \[*-+*\]*N*\ **-Bmin** \[*-+*\]*N*\ **-cmin** \[*-+*\]*N*\ **-mmin** \[*-+*\]*N* Find files **a**ccessed/**B**irthed/**c**hanged/**m**odified *N* minutes ago. **-anewer** *FILE*\ **-Bnewer** *FILE*\ **-cnewer** *FILE*\ **-mnewer** *FILE* Find files **a**ccessed/**B**irthed/**c**hanged/**m**odified more recently than *FILE* was modified. **-asince** *TIME*\ **-Bsince** *TIME*\ **-csince** *TIME*\ **-msince** *TIME* Find files **a**ccessed/**B**irthed/**c**hanged/**m**odified more recently than the ISO 8601-style timestamp *TIME*. See **-newer***XY* for examples of the timestamp format. **-atime** \[*-+*\]*N*\ **-Btime** \[*-+*\]*N*\ **-ctime** \[*-+*\]*N*\ **-mtime** \[*-+*\]*N* Find files **a**ccessed/**B**irthed/**c**hanged/**m**odified *N* days ago. - **-capable** Find files with POSIX.1e [**capabilities**(7)](/capabilities/7.md) set. - **-context** *GLOB* Find files whose SELinux context matches the *GLOB*. - **-depth** \[*-+*\]*N* Find files with depth *N*. - **-empty** Find empty files/directories. **-executable**\ **-readable**\ **-writable** Find files the current user can execute/read/write. **-false**\ **-true** Always false/true. - **-flags** \[*-+*\]*FLAGS* Find files with matching inode **FLAGS**. - **-fstype** *TYPE* Find files on file systems with the given *TYPE*. **-gid** \[*-+*\]*N*\ **-uid** \[*-+*\]*N* Find files owned by group/user ID *N*. **-group** *NAME*\ **-user** *NAME* Find files owned by the group/user *NAME*. - **-hidden** Find hidden files (those beginning with *.*). **-ilname** *GLOB*\ **-iname** *GLOB*\ **-ipath** *GLOB*\ **-iregex** *REGEX*\ **-iwholename** *GLOB* Case-insensitive versions of **-lname**/**-name**/**-path**/**-regex**/**-wholename**. - **-inum** \[*-+*\]*N* Find files with inode number *N*. - **-links** \[*-+*\]*N* Find files with *N* hard links. - **-lname** *GLOB* Find symbolic links whose target matches the *GLOB*. - **-name** *GLOB* Find files whose name matches the *GLOB*. - **-newer** *FILE* Find files newer than *FILE*. - **-newer***XY REFERENCE* Find files whose *X* time is newer than the *Y* time of *REFERENCE*. *X* and *Y* can be any of \[*aBcm*\] (*a*ccess/*B*irth/*c*hange/*m*odification). *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**\ **-nouser** Find files owned by nonexistent groups/users. **-path** *GLOB*\ **-wholename** *GLOB* Find files whose entire path matches the *GLOB*. - **-perm** \[*-+/*\]*MODE* Find files with a matching mode. - **-regex** *REGEX* Find files whose entire path matches the regular expression *REGEX*. - **-samefile** *FILE* Find hard links to *FILE*. - **-since** *TIME* Find files modified since the ISO 8601-style timestamp *TIME*. See **-newer***XY* for examples of the timestamp format. - **-size** \[*-+*\]*N*\[*cwbkMGTP*\] Find 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** Find files that occupy fewer disk blocks than expected. - **-type** \[*bcdlpfswD*\] Find files of the given type. The possible types are • *b*lock device\ • *c*haracter device\ • *d*irectory\ • *l*ink (symbolic)\ • *p*ipe\ • *f*ile (regular)\ • *s*ocket\ • *w*hiteout\ • *D*oor Multiple types can be given at once, separated by commas. For example, **-type** *d,f* matches both directories and regular files. - **-used** \[*-+*\]*N* Find files last accessed *N* days after they were changed. - **-xattr** Find files with extended attributes ([**xattr**(7)](/xattr/7.md)). - **-xattrname** *NAME* Find files with the extended attribute *NAME*. - **-xtype** \[*bcdlpfswD*\] Find files of the given type, following links when **-type** would not, and vice versa. ## ACTIONS **-delete**\ **-rm** Delete any found files (implies **-depth**). - **-exec** *command ... {} ;* Execute a command. - **-exec** *command ... {} +* Execute a command with multiple files at once. - **-ok** *command ... {} ;* Prompt the user whether to execute a command. **-execdir** *command ... {} ;*\ **-execdir** *command ... {} +*\ **-okdir** *command ... {} ;* Like **-exec**/**-ok**, but run the command in the same directory as the found file(s). - **-exit** \[*STATUS*\] Exit immediately with the given status (*0* if unspecified). **-fls** *FILE*\ **-fprint** *FILE*\ **-fprint0** *FILE*\ **-fprintf** *FILE FORMAT* Like **-ls**/**-print**/**-print0**/**-printf**, but write to *FILE* instead of standard output. - **-limit** *N* Quit once this action is evaluated *N* times. - **-ls** List files like **ls** *-dils*. - **-print** Print the path to the found file. - **-print0** Like **-print**, but use the null character ('\\0') as a separator rather than newlines. Useful in conjunction with **xargs** *-0*. - **-printf** *FORMAT* Print according to a format string (see [**find**(1)](/find/1.md)). These additional format directives are supported: - %w The file's birth time, in the same format as %a/%c/%t. - %W*k* Field *k* of the file's birth time, in the same format as %A*k*/%C*k*/%T*k*. - **-printx** Like **-print**, but escape whitespace and quotation characters, to make the output safe for [**xargs**(1)](/xargs/1.md). Consider using **-print0** and **xargs** *-0* instead. - **-prune** Don'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** Quit immediately. ## ENVIRONMENT Certain environment variables affect the behavior of **bfs**. **LANG**\ **LC\_\*** Specifies the [**locale**(7)](/locale/7.md) 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)](/ls/1.md) does (see [**dir\_colors**(5)](/dir_colors/5.md)). **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)](/less/1.md), if found on the current **PATH**, otherwise [**more**(1)](/more/1.md). - **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)](/find/1.md). 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)](/find/1.md) implementations use 512-byte blocks, while GNU [**find**(1)](/find/1.md) 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)](/find/1.md). ## EXAMPLES - **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)](/strip/1.md) on all executable files it finds, passing it multiple files at a time. ## BUGS https://github.com/tavianator/bfs/issues ## AUTHOR Tavian Barnes \ https://tavianator.com/projects/bfs.html ## SEE ALSO [**find**(1)](/find/1.md), [**locate**(1)](/locate/1.md), [**xargs**(1)](/xargs/1.md)