1BFS(1) General Commands Manual BFS(1)
2
6 bfs - breadth-first search for your files
7
9 bfs [flags...] [paths...] [expression...]
10 flags (-H/-L/-P etc.), paths, and expressions may be freely mixed in
12 any order.
13
15 bfs is a breadth-first version of the UNIX find(1) command.
16 bfs supports almost every feature from every major find(1) implementa‐
18 tion, so your existing command lines should work as-is. It also adds
19 some features of its own, such as a more forgiving command line parser
20 and some additional options.
21 Each path specified on the command line is treated as a starting path
23 to search through. If no paths are specified, the current directory
24 (.) is searched by default.
25 Like find(1), bfs interprets its arguments as a short-circuiting Bool‐
27 ean expression. For example,
28 bfs \( -name '*.txt' -or -lname '*.txt' \) -and -print
30 will print the all the paths that are either .txt files or symbolic
32 links to .txt files. -and is implied between two consecutive expres‐
33 sions, so this is equivalent:
34 bfs \( -name '*.txt' -or -lname '*.txt' \) -print
36 Finally, -print is implied if no actions are specified, so this too is
38 equivalent:
39 bfs -name '*.txt' -or -lname '*.txt'
41 Most options that take a numeric argument N will also accept -N or +N.
43 -N means "less than N," and +N means "greater than N."
44
46 -H Follow symbolic links on the command line, but not while search‐
47 ing.
48 -L Follow all symbolic links.
50 -P Never follow symbolic links (the default).
52 -E Use extended regular expressions (same as -regextype posix-ex‐
54 tended).
55 -X Filter out files with non-xargs(1)-safe names.
57 -d Search in post-order (same as -depth).
59 -s Visit directory entries in sorted order. The sorting takes
61 place within each directory separately, which makes it different
62 from bfs ... | sort, but still provides a deterministic order‐
63 ing.
64 -x Don't descend into other mount points (same as -xdev).
66 -f PATH
68 Treat PATH as a path to search (useful if it begins with a
69 dash).
70 -D FLAG
72 Turn on a debugging flag (see -D help).
73 -ON
75 Enable optimization level N (default: 3).
76 -O0 Disable all optimizations.
78 -O1 Basic logical simplifications.
80 -O2 All -O1 optimizations, plus dead code elimination and
82 data flow analysis.
83 -O3 All -O2 optimizations, plus re-order expressions to re‐
85 duce expected cost.
86 -O4/-Ofast
88 All optimizations, including aggressive optimizations
89 that may alter the observed behavior in corner cases.
90 -S bfs|dfs|ids|eds
92 Choose the search strategy.
93 bfs Breadth-first search (the default).
95 dfs Depth-first search. Uses less memory than breadth-first
97 search, but is typically slower to return relevant re‐
98 sults.
99 ids Iterative deepening search. Performs repeated depth-
101 first searches with increasing depth limits. This gives
102 results in the same order as breadth-first search, but
103 with the reduced memory consumption of depth-first
104 search. Tends to be very slow in practice, so use it
105 only if you absolutely need breadth-first ordering, but
106 -S bfs consumes too much memory.
107 eds Exponential deepening search. A compromise between
109 breadth- and depth-first search, which searches exponen‐
110 tially increasing depth ranges (e.g 0-1, 1-2, 2-4, 4-8,
111 etc.). Provides many of the benefits of breadth-first
112 search with depth-first's reduced memory consumption.
113 Typically far faster than -S ids.
114
116 ( expression )
117 Parentheses are used for grouping expressions together. You'll
118 probably have to write \( expression \) to avoid the parentheses
119 being interpreted by the shell.
120 ! expression
122 -not expression
123 The "not" operator: returns the negation of the truth value of
124 the expression. You may have to write \! expression to avoid !
125 being interpreted by the shell.
126 expression expression
128 expression -a expression
129 expression -and expression
130 Short-circuiting "and" operator: if the left-hand expression is
131 true, returns the right-hand expression; otherwise, returns
132 false.
133 expression -o expression
135 expression -or expression
136 Short-circuiting "or" operator: if the left-hand expression is
137 false, returns the right-hand expression; otherwise, returns
138 true.
139 expression , expression
141 The "comma" operator: evaluates the left-hand expression but
142 discards the result, returning the right-hand expression.
143
145 -exclude expression
146 Exclude all paths matching the expression from the search. This
147 is more powerful than -prune, because it applies even when the
148 expression wouldn't otherwise be evaluated, due to -depth or
149 -mindepth for example. Exclusions are always applied before
150 other expressions, so it may be least confusing to put them
151 first on the command line.
152
154 -color
155 -nocolor
156 Turn colors on or off (default: -color if outputting to a termi‐
157 nal, -nocolor otherwise).
158 -daystart
160 Measure time relative to the start of today.
161 -depth Search in post-order (descendents first).
163 -follow
165 Follow all symbolic links (same as -L).
166 -files0-from FILE
168 Treat the NUL ('\0')-separated paths in FILE as starting points
169 for the search. Pass -files0-from - to read the paths from
170 standard input.
171 -ignore_readdir_race
173 -noignore_readdir_race
174 Whether to report an error if bfs detects that the file tree is
175 modified during the search (default: -noignore_readdir_race).
176 -maxdepth N
178 -mindepth N
179 Ignore files deeper/shallower than N.
180 -mount Don't descend into other mount points (same as -xdev for now,
182 but will skip mount points entirely in the future).
183 -nohidden
185 Exclude hidden files and directories.
186 -noleaf
188 Ignored; for compatibility with GNU find.
189 -regextype TYPE
191 Use TYPE-flavored regexes (default: posix-basic; see -regextype
192 help).
193 -status
195 Display a status bar while searching.
196 -unique
198 Skip any files that have already been seen. Particularly useful
199 along with -L.
200 -warn
202 -nowarn
203 Turn on or off warnings about the command line.
204 -xdev Don't descend into other mount points.
206
208 -acl Find files with a non-trivial Access Control List (acl(5)).
209 -amin [-+]N
211 -Bmin [-+]N
212 -cmin [-+]N
213 -mmin [-+]N
214 Find files accessed/Birthed/changed/modified N minutes ago.
215 -anewer FILE
217 -Bnewer FILE
218 -cnewer FILE
219 -mnewer FILE
220 Find files accessed/Birthed/changed/modified more recently than
221 FILE was modified.
222 -asince TIME
224 -Bsince TIME
225 -csince TIME
226 -msince TIME
227 Find files accessed/Birthed/changed/modified more recently than
228 the ISO 8601-style timestamp TIME. See -newerXY for examples of
229 the timestamp format.
230 -atime [-+]N
232 -Btime [-+]N
233 -ctime [-+]N
234 -mtime [-+]N
235 Find files accessed/Birthed/changed/modified N days ago.
236 -capable
238 Find files with POSIX.1e capabilities(7) set.
239 -depth [-+]N
241 Find files with depth N.
242 -empty Find empty files/directories.
244 -executable
246 -readable
247 -writable
248 Find files the current user can execute/read/write.
249 -false
251 -true
252 Always false/true.
253 -fstype TYPE
255 Find files on file systems with the given TYPE.
256 -gid [-+]N
258 -uid [-+]N
259 Find files owned by group/user ID N.
260 -group NAME
262 -user NAME
263 Find files owned by the group/user NAME.
264 -hidden
266 Find hidden files (those beginning with .).
267 -ilname GLOB
269 -iname GLOB
270 -ipath GLOB
271 -iregex REGEX
272 -iwholename GLOB
273 Case-insensitive versions of -lname/-name/-path/-regex/-whole‐
274 name.
275 -inum [-+]N
277 Find files with inode number N.
278 -links [-+]N
280 Find files with N hard links.
281 -lname GLOB
283 Find symbolic links whose target matches the GLOB.
284 -name GLOB
286 Find files whose name matches the GLOB.
287 -newer FILE
289 Find files newer than FILE.
290 -newerXY REFERENCE
292 Find files whose X time is newer than the Y time of REFERENCE.
293 X and Y can be any of [aBcm] (access/Birth/change/modification).
294 Y may also be t to parse REFERENCE as an ISO 8601-style time‐
295 stamp. For example:
296 1991-12-14
298 1991-12-14T03:00
299 1991-12-14T03:00-07:00
300 1991-12-14T10:00Z
301 -nogroup
303 -nouser
304 Find files owned by nonexistent groups/users.
305 -path GLOB
307 -wholename GLOB
308 Find files whose entire path matches the GLOB.
309 -perm [-]MODE
311 Find files with a matching mode.
312 -regex REGEX
314 Find files whose entire path matches the regular expression
315 REGEX.
316 -samefile FILE
318 Find hard links to FILE.
319 -since TIME
321 Find files modified since the ISO 8601-style timestamp TIME.
322 See -newerXY for examples of the timestamp format.
323 -size [-+]N[cwbkMGTP]
325 Find files with the given size, in 1-byte characters, 2-byte
326 words, 512-byte blocks (default), or kiB/MiB/GiB/TiB/PiB.
327 -sparse
329 Find files that occupy fewer disk blocks than expected.
330 -type [bcdlpfswD]
332 Find files of the given type. Possible types are block device,
333 character device, directory, symbolic link, pipe, regular file,
334 socket, whiteout, and Door.
335 -used [-+]N
337 Find files last accessed N days after they were changed.
338 -xattr Find files with extended attributes (xattr(7)).
340 -xattrname NAME
342 Find files with the extended attribute NAME.
343 -xtype [bcdlpfswD]
345 Find files of the given type, following links when -type would
346 not, and vice versa.
347
349 -delete
350 -rm
351 Delete any found files (implies -depth).
352 -exec command ... {} ;
354 Execute a command.
355 -exec command ... {} +
357 Execute a command with multiple files at once.
358 -ok command ... {} ;
360 Prompt the user whether to execute a command.
361 -execdir command ... {} ;
363 -execdir command ... {} +
364 -okdir command ... {} ;
365 Like -exec/-ok, but run the command in the same directory as the
366 found file(s).
367 -exit [STATUS]
369 Exit immediately with the given status (0 if unspecified).
370 -fls FILE
372 -fprint FILE
373 -fprint0 FILE
374 -fprintf FILE FORMAT
375 Like -ls/-print/-print0/-printf, but write to FILE instead of
376 standard output.
377 -ls List files like ls -dils.
379 -print Print the path to the found file.
381 -print0
383 Like -print, but use the null character ('\0') as a separator
384 rather than newlines. Useful in conjunction with xargs -0.
385 -printf FORMAT
387 Print according to a format string (see find(1)). These addi‐
388 tional format directives are supported:
389 %w The file's birth time, in the same format as %a/%c/%t.
391 %Wk Field k of the file's birth time, in the same format as
393 %Ak/%Ck/%Tk.
394 -printx
396 Like -print, but escape whitespace and quotation characters, to
397 make the output safe for xargs(1). Consider using -print0 and
398 xargs -0 instead.
399 -prune Don't descend into this directory.
401 -quit Quit immediately.
403 -version
405 Print version information.
406 -help Print usage information.
408
410 Certain environment variables affect the behavior of bfs.
411 LANG
413 LC_*
414 Specifies the locale(7) in use for various things. bfs is not
415 (yet) translated to any languages except English, but the locale
416 will still affect the format of printed values. Yes/no prompts
417 (e.g. from -ok) will also be interpreted according to the cur‐
418 rent locale.
419 LS_COLORS
421 BFS_COLORS
422 Controls the colors used when displaying file paths if -color is
423 enabled. bfs interprets LS_COLORS the same way GNU ls(1) does
424 (see dir_colors(5)). BFS_COLORS can be used to customize bfs
425 without affecting other commands.
426 NO_COLOR
428 Causes bfs to default to -nocolor if it is set (see https://no-
429 color.org/).
430 PAGER Specifies the pager used for -help output. Defaults to more(1).
432 POSIXLY_CORRECT
434 Makes bfs conform more strictly to the POSIX.1-2017 specifica‐
435 tion for find(1). Currently this just disables warnings by de‐
436 fault. It does not disable bfs's various extensions to the base
437 POSIX functionality.
438
440 bfs With no arguments, bfs prints all files under the current direc‐
441 tory in breadth-first order.
442 bfs -name '*.txt'
444 Prints all the .txt files under the current directory. *.txt is
445 quoted to ensure the glob is processed by bfs rather than the
446 shell.
447 bfs -name access_log -L /var
449 Finds all files named access_log under /var, following symbolic
450 links. bfs allows flags and paths to appear anywhere on the
451 command line.
452 bfs ~ -not -user $USER
454 Prints all files in your home directory not owned by you.
455 bfs -xtype l
457 Finds broken symbolic links.
458 bfs -name config -exclude -name .git
460 Finds all files named config, skipping every .git directory.
461 bfs -type f -executable -exec strip '{}' +
463 Runs strip(1) on all executable files it finds, passing it mul‐
464 tiple files at a time.
465
467 https://github.com/tavianator/bfs/issues
468
470 Tavian Barnes <tavianator@tavianator.com>
471 https://tavianator.com/projects/bfs.html
473
475 find(1), locate(1), xargs(1)
476 BFS(1)