bfs − breadth-first search for your files
bfs [flags...] [paths...] [expression...]
flags (−H/−L/−P etc.), paths, and expressions may be freely mixed in any order.
bfs is a breadth-first version of the UNIX find(1) command.
bfs 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.
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 the 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."
|
−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).
( 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.
−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.
−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 |
Don’t descend into other mount points (same as −xdev for now, but will skip mount points entirely in the future). |
−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 resular 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. |
|
−acl |
Find files with a non-trivial Access Control List (acl(5)). |
−amin
[−+]N
−Bmin [−+]N
−cmin [−+]N
−mmin [−+]N
Find files accessed/Birthed/changed/modified N minutes ago.
−anewer
FILE
−Bnewer FILE
−cnewer FILE
−mnewer FILE
Find files accessed/Birthed/changed/modified more recently than FILE was modified.
−asince
TIME
−Bsince TIME
−csince TIME
−msince TIME
Find files accessed/Birthed/changed/modified more recently than the ISO 8601-style timestamp TIME. See −newerXY for examples of the timestamp format.
−atime
[−+]N
−Btime [−+]N
−ctime [−+]N
−mtime [−+]N
Find files accessed/Birthed/changed/modified N days ago.
−capable
Find files with POSIX.1e capabilities(7) set.
−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.
−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.
−newerXY REFERENCE
Find 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
−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 −newerXY 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
•
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
Find files last accessed N days after they were changed.
|
−xattr |
Find files with extended attributes (xattr(7)). |
−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.
−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.
|
−ls |
List files like ls −dils. |
|||
|
|
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)). 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 escape whitespace and quotation characters, to make the output safe for xargs(1). 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. |
Certain environment variables affect the behavior of bfs.
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).
|
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.
https://github.com/tavianator/bfs/issues
Tavian Barnes <[email protected]>
https://tavianator.com/projects/bfs.html
find(1), locate(1), xargs(1)