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 -jN Search with N threads in parallel (default: number of CPUs, up
116 to 8).
117
119 ( expression )
120 Parentheses are used for grouping expressions together. You'll
121 probably have to write \( expression \) to avoid the parentheses
122 being interpreted by the shell.
123 ! expression
125 -not expression
126 The "not" operator: returns the negation of the truth value of
127 the expression. You may have to write \! expression to avoid !
128 being interpreted by the shell.
129 expression expression
131 expression -a expression
132 expression -and expression
133 Short-circuiting "and" operator: if the left-hand expression is
134 true, returns the right-hand expression; otherwise, returns
135 false.
136 expression -o expression
138 expression -or expression
139 Short-circuiting "or" operator: if the left-hand expression is
140 false, returns the right-hand expression; otherwise, returns
141 true.
142 expression , expression
144 The "comma" operator: evaluates the left-hand expression but
145 discards the result, returning the right-hand expression.
146
148 -exclude expression
149 Exclude all paths matching the expression from the search. This
150 is more powerful than -prune, because it applies even when the
151 expression wouldn't otherwise be evaluated, due to -depth or
152 -mindepth for example. Exclusions are always applied before
153 other expressions, so it may be least confusing to put them
154 first on the command line.
155 -help
157 --help
158 Print usage information, and exit immediately (without parsing
159 the rest of the command line or processing any files).
160 -version
162 --version
163 Print version information, and exit immediately.
164
166 -color
167 -nocolor
168 Turn colors on or off (default: -color if outputting to a termi‐
169 nal, -nocolor otherwise).
170 -daystart
172 Measure time relative to the start of today.
173 -depth Search in post-order (descendents first).
175 -follow
177 Follow all symbolic links (same as -L).
178 -files0-from FILE
180 Treat the NUL ('\0')-separated paths in FILE as starting points
181 for the search. Pass -files0-from - to read the paths from
182 standard input.
183 -ignore_readdir_race
185 -noignore_readdir_race
186 Whether to report an error if bfs detects that the file tree is
187 modified during the search (default: -noignore_readdir_race).
188 -maxdepth N
190 -mindepth N
191 Ignore files deeper/shallower than N.
192 -mount Don't descend into other mount points (same as -xdev for now,
194 but will skip mount points entirely in the future).
195 -nohidden
197 Exclude hidden files and directories.
198 -noleaf
200 Ignored; for compatibility with GNU find.
201 -regextype TYPE
203 Use TYPE-flavored regular expressions. The possible types are
204 posix-basic
206 POSIX basic regular expressions (the default).
207 posix-extended
209 POSIX extended resular expressions.
210 ed Like ed(1) (same as posix-basic).
212 emacs Like emacs(1).
214 grep Like grep(1).
216 sed Like sed(1) (same as posix-basic).
218 See regex(7) for a description of regular expression syntax.
220 -status
222 Display a status bar while searching.
223 -unique
225 Skip any files that have already been seen. Particularly useful
226 along with -L.
227 -warn
229 -nowarn
230 Turn on or off warnings about the command line.
231 -xdev Don't descend into other mount points.
233
235 -acl Find files with a non-trivial Access Control List (acl(5)).
236 -amin [-+]N
238 -Bmin [-+]N
239 -cmin [-+]N
240 -mmin [-+]N
241 Find files accessed/Birthed/changed/modified N minutes ago.
242 -anewer FILE
244 -Bnewer FILE
245 -cnewer FILE
246 -mnewer FILE
247 Find files accessed/Birthed/changed/modified more recently than
248 FILE was modified.
249 -asince TIME
251 -Bsince TIME
252 -csince TIME
253 -msince TIME
254 Find files accessed/Birthed/changed/modified more recently than
255 the ISO 8601-style timestamp TIME. See -newerXY for examples of
256 the timestamp format.
257 -atime [-+]N
259 -Btime [-+]N
260 -ctime [-+]N
261 -mtime [-+]N
262 Find files accessed/Birthed/changed/modified N days ago.
263 -capable
265 Find files with POSIX.1e capabilities(7) set.
266 -depth [-+]N
268 Find files with depth N.
269 -empty Find empty files/directories.
271 -executable
273 -readable
274 -writable
275 Find files the current user can execute/read/write.
276 -false
278 -true
279 Always false/true.
280 -fstype TYPE
282 Find files on file systems with the given TYPE.
283 -gid [-+]N
285 -uid [-+]N
286 Find files owned by group/user ID N.
287 -group NAME
289 -user NAME
290 Find files owned by the group/user NAME.
291 -hidden
293 Find hidden files (those beginning with .).
294 -ilname GLOB
296 -iname GLOB
297 -ipath GLOB
298 -iregex REGEX
299 -iwholename GLOB
300 Case-insensitive versions of -lname/-name/-path/-regex/-whole‐
301 name.
302 -inum [-+]N
304 Find files with inode number N.
305 -links [-+]N
307 Find files with N hard links.
308 -lname GLOB
310 Find symbolic links whose target matches the GLOB.
311 -name GLOB
313 Find files whose name matches the GLOB.
314 -newer FILE
316 Find files newer than FILE.
317 -newerXY REFERENCE
319 Find files whose X time is newer than the Y time of REFERENCE.
320 X and Y can be any of [aBcm] (access/Birth/change/modification).
321 Y may also be t to parse REFERENCE as an ISO 8601-style time‐
322 stamp. For example:
323 • 1991-12-14
325 • 1991-12-14T03:00
326 • 1991-12-14T03:00-07:00
327 • '1991-12-14 10:00Z'
328 -nogroup
330 -nouser
331 Find files owned by nonexistent groups/users.
332 -path GLOB
334 -wholename GLOB
335 Find files whose entire path matches the GLOB.
336 -perm [-]MODE
338 Find files with a matching mode.
339 -regex REGEX
341 Find files whose entire path matches the regular expression
342 REGEX.
343 -samefile FILE
345 Find hard links to FILE.
346 -since TIME
348 Find files modified since the ISO 8601-style timestamp TIME.
349 See -newerXY for examples of the timestamp format.
350 -size [-+]N[cwbkMGTP]
352 Find files with the given size. The unit can be one of
353 • chars (1 byte)
355 • words (2 bytes)
356 • blocks (512 bytes, the default)
357 • kiB (1024 bytes)
358 • MiB (1024 kiB)
359 • GiB (1024 MiB)
360 • TiB (1024 GiB)
361 • PiB (1024 TiB)
362 -sparse
364 Find files that occupy fewer disk blocks than expected.
365 -type [bcdlpfswD]
367 Find files of the given type. The possible types are
368 • block device
370 • character device
371 • directory
372 • link (symbolic)
373 • pipe
374 • file (regular)
375 • socket
376 • whiteout
377 • Door
378 Multiple types can be given at once, separated by commas. For
380 example, -type d,f matches both directories and regular files.
381 -used [-+]N
383 Find files last accessed N days after they were changed.
384 -xattr Find files with extended attributes (xattr(7)).
386 -xattrname NAME
388 Find files with the extended attribute NAME.
389 -xtype [bcdlpfswD]
391 Find files of the given type, following links when -type would
392 not, and vice versa.
393
395 -delete
396 -rm
397 Delete any found files (implies -depth).
398 -exec command ... {} ;
400 Execute a command.
401 -exec command ... {} +
403 Execute a command with multiple files at once.
404 -ok command ... {} ;
406 Prompt the user whether to execute a command.
407 -execdir command ... {} ;
409 -execdir command ... {} +
410 -okdir command ... {} ;
411 Like -exec/-ok, but run the command in the same directory as the
412 found file(s).
413 -exit [STATUS]
415 Exit immediately with the given status (0 if unspecified).
416 -fls FILE
418 -fprint FILE
419 -fprint0 FILE
420 -fprintf FILE FORMAT
421 Like -ls/-print/-print0/-printf, but write to FILE instead of
422 standard output.
423 -ls List files like ls -dils.
425 -print Print the path to the found file.
427 -print0
429 Like -print, but use the null character ('\0') as a separator
430 rather than newlines. Useful in conjunction with xargs -0.
431 -printf FORMAT
433 Print according to a format string (see find(1)). These addi‐
434 tional format directives are supported:
435 %w The file's birth time, in the same format as %a/%c/%t.
437 %Wk Field k of the file's birth time, in the same format as
439 %Ak/%Ck/%Tk.
440 -printx
442 Like -print, but escape whitespace and quotation characters, to
443 make the output safe for xargs(1). Consider using -print0 and
444 xargs -0 instead.
445 -prune Don't descend into this directory. This has no effect if -depth
447 is enabled (either explicitly, or implicitly by -delete). Use
448 -exclude instead in that case.
449 -quit Quit immediately.
451
453 Certain environment variables affect the behavior of bfs.
454 LANG
456 LC_*
457 Specifies the locale(7) in use for various things. bfs is not
458 (yet) translated to any languages except English, but the locale
459 will still affect the format of printed values. Yes/no prompts
460 (e.g. from -ok) will also be interpreted according to the cur‐
461 rent locale.
462 LS_COLORS
464 BFS_COLORS
465 Controls the colors used when displaying file paths if -color is
466 enabled. bfs interprets LS_COLORS the same way GNU ls(1) does
467 (see dir_colors(5)). BFS_COLORS can be used to customize bfs
468 without affecting other commands.
469 NO_COLOR
471 Causes bfs to default to -nocolor if it is set (see https://no-
472 color.org/).
473 PAGER Specifies the pager used for -help output. Defaults to less(1),
475 if found on the current PATH, otherwise more(1).
476 PATH Used to resolve executables for -exec[dir] and -ok[dir].
478 POSIXLY_CORRECT
480 Makes bfs conform more strictly to the POSIX.1-2017 specifica‐
481 tion for find(1). Currently this has two effects:
482 • Disables warnings by default, because POSIX prohibits
484 writing to standard error (except for the -ok prompt),
485 unless the command also fails with a non-zero exit sta‐
486 tus.
487 • Makes -ls and -fls use 512-byte blocks instead of
489 1024-byte blocks. (POSIX does not specify these actions,
490 but BSD find(1) implementations use 512-byte blocks,
491 while GNU find(1) uses 1024-byte blocks by default.)
492 It does not disable bfs's various extensions to the base POSIX
494 functionality. POSIXLY_CORRECT has the same effects on GNU
495 find(1).
496
498 bfs With no arguments, bfs prints all files under the current direc‐
499 tory in breadth-first order.
500 bfs -name '*.txt'
502 Prints all the .txt files under the current directory. *.txt is
503 quoted to ensure the glob is processed by bfs rather than the
504 shell.
505 bfs -name access_log -L /var
507 Finds all files named access_log under /var, following symbolic
508 links. bfs allows flags and paths to appear anywhere on the
509 command line.
510 bfs ~ -not -user $USER
512 Prints all files in your home directory not owned by you.
513 bfs -xtype l
515 Finds broken symbolic links.
516 bfs -name config -exclude -name .git
518 Finds all files named config, skipping every .git directory.
519 bfs -type f -executable -exec strip {} +
521 Runs strip(1) on all executable files it finds, passing it mul‐
522 tiple files at a time.
523
525 https://github.com/tavianator/bfs/issues
526
528 Tavian Barnes <tavianator@tavianator.com>
529 https://tavianator.com/projects/bfs.html
531
533 find(1), locate(1), xargs(1)
534 BFS(1)