Something went wrong. Try again.
A breadth-first version of the UNIX find command tavianator.com/projects/bfs.html
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983.\" Copyright © Tavian Barnes <tavianator@tavianator.com>.\" SPDX-License-Identifier: 0BSD.TH BFS 1 2026-06-29 "bfs 4.1.4".SH NAMEbfs \- breadth-first search for your files.SH SYNOPSIS.B bfs.RB [ flags ...].RI [ paths ...].RB [ expression ...].PPflags.RB ( \-H / \-L / \-Petc.),.IR paths ,and.B expressionsmay be freely mixed in any order..SH DESCRIPTION.B bfsis a breadth-first version of the UNIX.BR find (1)command..PP.B bfssupports almost every feature from every major.BR 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..PPEach.I pathspecified on the command line is treated as a starting path to search through.If no paths are specified, the current directory.RI ( . )is searched by default..PPLike.BR find (1),.B bfsinterprets its arguments as a short-circuiting Boolean expression.For example,.PP.nf.RS.B bfs \e( \-name '*.txt' \-or \-lname '*.txt' \e) \-and \-print.RE.fi.PPwill print all the paths that are either .txt files or symbolic links to .txt files..B \-andis implied between two consecutive expressions, so this is equivalent:.PP.nf.RS.B bfs \e( \-name '*.txt' \-or \-lname '*.txt' \e) \-print.RE.fi.PPFinally,.B \-printis implied if no actions are specified, so this too is equivalent:.PP.nf.RS.B bfs \-name '*.txt' \-or \-lname '*.txt'.RE.fi.PPMost options that take a numeric argument.I Nwill also accept.I \-Nor.IR +N ..I \-Nmeans "less than.IR N ,"and.I +Nmeans "greater than.IR N .".SH FLAGS.TP.B \-HFollow symbolic links on the command line, but not while searching..TP.B \-LFollow all symbolic links..TP.B \-PNever follow symbolic links (the default)..TP.B \-EUse extended regular expressions (same as.B \-regextype.IR posix-extended )..TP.B \-XFilter out files with.RB non- xargs (1)-safenames..TP.B \-dSearch in post-order (same as.BR \-depth )..TP.B \-sVisit directory entries in sorted order.The sorting takes place within each directory separately, which makes it different from.B bfs ... |.BR sort ,but still provides a deterministic ordering..TP.B \-xDon't descend into other mount points (same as.BR \-xdev )..TP.BI "\-f " PATHTreat.I PATHas a path to search (useful if it begins with a dash)..TP.BI "\-D " FLAGTurn on a debugging flag (see.B \-D.IR help )..PP.BI \-O N.RSEnable optimization level.I N(default:.IR 3 )..TP.BI \-O 0Disable all optimizations..TP.BI \-O 1Basic logical simplifications..TP.BI \-O 2All.BI \-O 1optimizations, plus dead code elimination and data flow analysis..TP.BI \-O 3All.BI \-O 2optimizations, plus re-order expressions to reduce expected cost..TP\fB\-O\fI4\fR/\fB\-O\fIfast\fRAll optimizations, including aggressive optimizations that may alter the observed behavior in corner cases..RE.PP\fB\-S \fIbfs\fR|\fIdfs\fR|\fIids\fR|\fIeds\fR.RSChoose the search strategy..TP.I bfsBreadth-first search (the default)..TP.I dfsDepth-first search.Uses less memory than breadth-first search, but is typically slower to return relevant results..TP.I idsIterative 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.B \-S.I bfsconsumes too much memory..TP.I edsExponential 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.B \-S.IR ids ..RE.TP.BI \-j NSearch with.I Nthreads in parallel (default: number of CPUs, up to.IR 8 )..SH OPERATORS.TP.BI "( " expression " )"Parentheses are used for grouping expressions together.You'll probably have to write.B \e(.I expression.B \e)to avoid the parentheses being interpreted by the shell..PP\fB! \fIexpression\fR.br.B \-not.I expression.RSThe "not" operator: returns the negation of the truth value of the.IR expression .You may have to write \fB\e! \fIexpression\fR to avoid.B !being interpreted by the shell..RE.PP.I expression expression.br.I expression.B \-a.I expression.br.I expression.B \-and.I expression.RSShort-circuiting "and" operator: if the left-hand.I expressionis.BR true ,returns the right-hand.IR expression ;otherwise, returns.BR false ..RE.PP.I expression.B \-o.I expression.br.I expression.B \-or.I expression.RSShort-circuiting "or" operator: if the left-hand.I expressionis.BR false ,returns the right-hand.IR expression ;otherwise, returns.BR true ..RE.TP.IB "expression " , " expression"The "comma" operator: evaluates the left-hand.I expressionbut discards the result, returning the right-hand.IR expression ..SH SPECIAL FORMS.TP.BI "\-exclude " expressionExclude all paths matching the.I expressionfrom the search.This is more powerful than.BR \-prune ,because it applies even when the expression wouldn't otherwise be evaluated, due to.B \-depthor.B \-mindepthfor example.Exclusions are always applied before other expressions, so it may be least confusing to put them first on the command line..PP.B \-help.br.B \-\-help.RSPrint usage information, and exit immediately (without parsing the rest of the command line or processing any files)..RE.PP.B \-version.br.B \-\-version.RSPrint version information, and exit immediately..RE.SH OPTIONS.B \-color.br.B \-nocolor.RSTurn colors on or off (default:.B \-colorif outputting to a terminal,.B \-nocolorotherwise)..RE.TP.B \-daystartMeasure time relative to the start of today..TP.B \-depthSearch in post-order (descendents first)..TP.B \-followFollow all symbolic links (same as.BR \-L )..TP.BI "\-files0\-from " FILETreat the NUL ('\e0')-separated paths in.I FILEas starting points for the search.Pass.B \-files0\-from.I \-to read the paths from standard input..PP.B \-ignore_readdir_race.br.B \-noignore_readdir_race.RSWhether to report an error if.B bfsdetects that the file tree is modified during the search (default:.BR \-noignore_readdir_race )..RE.PP.B \-maxdepth.I N.br.B \-mindepth.I N.RSIgnore files deeper/shallower than.IR N ..RE.TP.B \-mountExclude mount points entirely from the results..TP.B \-noerrorIgnore any errors that occur during traversal..TP.B \-nohiddenExclude hidden files and directories..TP.B \-noleafIgnored; for compatibility with GNU find..TP.BI "\-regextype " TYPEUse.IR TYPE -flavoredregular expressions.The possible types are.RS.TP.I posix-basicPOSIX basic regular expressions (the default)..TP.I posix-extendedPOSIX extended regular expressions..TP.I edLike.BR ed (1)(same as.IR posix-basic )..TP.I emacsLike.BR emacs (1)..TP.I grepLike.BR grep (1)..TP.I sedLike.BR sed (1)(same as.IR posix-basic )..PPSee.BR regex (7)for a description of regular expression syntax..RE.TP.B \-statusDisplay a status bar while searching..TP.B \-uniqueSkip any files that have already been seen.Particularly useful along with.BR \-L ..PP.B \-warn.br.B \-nowarn.RSTurn on or off warnings about the command line..RE.TP.B \-xdevDon't descend into other mount points.Unlike.BR \-mount ,the mount point itself is still included..SH TESTS.TP.B \-aclFind files with a non-trivial Access Control List.RB ( acl (5))..PP\fB\-amin\fR [\fI\-+\fR]\fIN\fR.br\fB\-Bmin\fR [\fI\-+\fR]\fIN\fR.br\fB\-cmin\fR [\fI\-+\fR]\fIN\fR.br\fB\-mmin\fR [\fI\-+\fR]\fIN\fR.RSFind files.BR a ccessed/ B irthed/ c hanged/ m odified.I Nminutes ago..RE.PP.B \-anewer.I FILE.br.B \-Bnewer.I FILE.br.B \-cnewer.I FILE.br.B \-mnewer.I FILE.RSFind files.BR a ccessed/ B irthed/ c hanged/ m odifiedmore recently than.I FILEwas modified..RE.PP.B \-asince.I TIME.br.B \-Bsince.I TIME.br.B \-csince.I TIME.br.B \-msince.I TIME.RSFind files.BR a ccessed/ B irthed/ c hanged/ m odifiedmore recently than the ISO 8601-style timestamp.IR TIME .See.BI \-newer XYfor examples of the timestamp format..RE.PP\fB\-atime\fR [\fI\-+\fR]\fIN\fR.br\fB\-Btime\fR [\fI\-+\fR]\fIN\fR.br\fB\-ctime\fR [\fI\-+\fR]\fIN\fR.br\fB\-mtime\fR [\fI\-+\fR]\fIN\fR.RSFind files.BR a ccessed/ B irthed/ c hanged/ m odified.I Ndays ago..RE.TP.B \-capableFind files with POSIX.1e.BR capabilities (7)set..TP.BI "\-context " GLOBFind files whose SELinux context matches the.IR GLOB ..TP\fB\-depth\fR [\fI\-+\fR]\fIN\fRFind files with depth.IR N ..TP.B \-emptyFind empty files/directories..PP.B \-executable.br.B \-readable.br.B \-writable.RSFind files the current user can execute/read/write..RE.PP.B \-false.br.B \-true.RSAlways false/true..RE.TP\fB\-flags\fR [\fI\-+\fR]\fIFLAGS\fRFind files with matching inode.BR FLAGS ..TP.BI "\-fstype " TYPEFind files on file systems with the given.IR TYPE ..PP\fB\-gid\fR [\fI\-+\fR]\fIN\fR.br\fB\-uid\fR [\fI\-+\fR]\fIN\fR.RSFind files owned by group/user ID.IR N ..RE.PP.B \-group.I NAME.br.B \-user.I NAME.RSFind files owned by the group/user.IR NAME ..RE.TP.B \-hiddenFind hidden files (those beginning with.IR . )..PP.B \-ilname.I GLOB.br.B \-iname.I GLOB.br.B \-ipath.I GLOB.br.B \-iregex.I REGEX.br.B \-iwholename.I GLOB.RSCase-insensitive versions of.BR \-lname / \-name / \-path / \-regex / \-wholename ..RE.TP\fB\-inum\fR [\fI\-+\fR]\fIN\fRFind files with inode number.IR N ..TP\fB\-links\fR [\fI\-+\fR]\fIN\fRFind files with.I Nhard links..TP.BI "\-lname " GLOBFind symbolic links whose target matches the.IR GLOB ..TP.BI "\-name " GLOBFind files whose name matches the.IR GLOB ..TP.BI "\-newer " FILEFind files newer than.IR FILE ..TP.BI \-newer "XY REFERENCE"Find files whose.I Xtime is newer than the.I Ytime of.IR REFERENCE ..I Xand.I Ycan be any of.RI [ aBcm ].RI ( a ccess/ B irth/ c hange/ m odification)..I Ymay also be.I tto parse.I REFERENCEas an ISO 8601-style timestamp. For example:.PP.RS.nf\(bu \fI1991-12-14\fR\(bu \fI1991-12-14T03:00\fR\(bu \fI1991-12-14T03:00-07:00\fR\(bu '\fI1991-12-14 10:00Z\fR'.fi.RE.PP.B \-nogroup.br.B \-nouser.RSFind files owned by nonexistent groups/users..RE.PP.B \-path.I GLOB.br.B \-wholename.I GLOB.RSFind files whose entire path matches the.IR GLOB ..RE.TP\fB\-perm\fR [\fI\-+/\fR]\fIMODE\fRFind files with a matching mode..TP.BI "\-regex " REGEXFind files whose entire path matches the regular expression.IR REGEX ..TP.BI "\-samefile " FILEFind hard links to.IR FILE ..TP.BI "\-since " TIMEFind files modified since the ISO 8601-style timestamp.IR TIME .See.BI \-newer XYfor examples of the timestamp format..TP\fB\-size\fR [\fI\-+\fR]\fIN\fR[\fIcwbkMGTP\fR]Find files with the given size.The unit can be one of.PP.RS.nf\(bu \fIc\fRhars (1 byte)\(bu \fIw\fRords (2 bytes)\(bu \fIb\fRlocks (512 bytes, the default)\(bu \fIk\fRiB (1024 bytes)\(bu \fIM\fRiB (1024 kiB)\(bu \fIG\fRiB (1024 MiB)\(bu \fIT\fRiB (1024 GiB)\(bu \fIP\fRiB (1024 TiB).fi.RE.TP.B \-sparseFind files that occupy fewer disk blocks than expected..TP\fB\-type\fR [\fIbcdlpfswD\fR]Find files of the given type.The possible types are.PP.RS\(bu.IR b lockdevice.br\(bu.IR c haracterdevice.br\(bu.IR d irectory.br\(bu.IR l ink(symbolic).br\(bu.IR p ipe.br\(bu.IR f ile(regular).br\(bu.IR s ocket.br\(bu.IR w hiteout.br\(bu.IR D oor.PPMultiple types can be given at once, separated by commas.For example,.B \-type.I d,fmatches both directories and regular files..RE.TP\fB\-used\fR [\fI\-+\fR]\fIN\fRFind files last accessed.I Ndays after they were changed..TP.B \-xattrFind files with extended attributes.RB ( xattr (7))..TP.BI "\-xattrname " NAMEFind files with the extended attribute.IR NAME ..TP\fB\-xtype\fR [\fIbcdlpfswD\fR]Find files of the given type, following links when.B \-typewould not, and vice versa..SH ACTIONS.B \-delete.br.B \-rm.RSDelete any found files (implies.BR \-depth )..RE.TP.BI "\-exec " "command ... {} ;"Execute a command..TP.BI "\-exec " "command ... {} +"Execute a command with multiple files at once..TP.BI "\-ok " "command ... {} ;"Prompt the user whether to execute a command..PP.B \-execdir.I command ... {} ;.br.B \-execdir.I command ... {} +.br.B \-okdir.I command ... {} ;.RSLike.BR \-exec / \-ok ,but run the command in the same directory as the found file(s)..RE.TP\fB\-exit\fR [\fISTATUS\fR]Exit immediately with the given status.RI ( 0if unspecified)..PP.B \-fls.I FILE.br.B \-fprint.I FILE.br.B \-fprint0.I FILE.br.B \-fprintf.I FILE FORMAT.RSLike.BR \-ls / \-print / \-print0 / \-printf ,but write to.I FILEinstead of standard output..RE.TP.BI "\-limit " NQuit once this action is evaluated.I Ntimes..TP.B \-lsList files like.B ls.IR \-dils ..TP.B \-printPrint the path to the found file..TP.B \-print0Like.BR \-print ,but use the null character ('\e0') as a separator rather than newlines.Useful in conjunction with.B xargs.IR \-0 ..TP.BI "\-printf " FORMATPrint according to a format string (see.BR find (1)).These additional format directives are supported:.RS.TP%wThe file's birth time, in the same format as %a/%c/%t..TP.RI %W kField.I kof the file's birth time, in the same format as.RI %A k /%C k /%T k ..RE.TP.B \-printxLike.BR \-print ,but escape whitespace and quotation characters, to make the output safe for.BR xargs (1).Consider using.B \-print0and.B xargs.I \-0instead..TP.B \-pruneDon't descend into this directory.This has no effect if.B \-depthis enabled (either explicitly, or implicitly by.BR \-delete ).Use.B \-excludeinstead in that case..TP.B \-quitQuit immediately..SH ENVIRONMENTCertain environment variables affect the behavior of.BR bfs ..PP.B LANG.br.B LC_*.RSSpecifies the.BR locale (7)in use for various things..B bfsis 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.BR \-ok )will also be interpreted according to the current locale..RE.PP.B LS_COLORS.br.B BFS_COLORS.RSControls the colors used when displaying file paths if.B \-coloris enabled..B bfsinterprets.B LS_COLORSthe same way GNU.BR ls (1)does (see.BR dir_colors (5))..B BFS_COLORScan be used to customize.B bfswithout affecting other commands..RE.TP.B NO_COLORCauses.B bfsto default to.B \-nocolorif it is set (see https://no-color.org/)..TP.B PAGERSpecifies the pager used for.B \-helpoutput.Defaults to.BR less (1),if found on the current.BR PATH ,otherwise.BR more (1)..TP.B PATHUsed to resolve executables for.BR \-exec [ dir ]and.BR \-ok [ dir ]..TP.B POSIXLY_CORRECTMakes.B bfsconform more strictly to the POSIX.1-2017 specification for.BR find (1).Currently this has two effects:.RS.IP \(buDisables warnings by default, because POSIX prohibits writing to standard error (except for the.B \-okprompt), unless the command also fails with a non-zero exit status..IP \(buMakes.B \-lsand.B \-flsuse 512-byte blocks instead of 1024-byte blocks.(POSIX does not specify these actions, but BSD.BR find (1)implementations use 512-byte blocks, while GNU.BR find (1)uses 1024-byte blocks by default.).PPIt does not disable.BR bfs 'svarious extensions to the base POSIX functionality..B POSIXLY_CORRECThas the same effects on GNU.BR find (1)..RE.SH EXAMPLES.TP.B bfsWith no arguments,.B bfsprints all files under the current directory in breadth-first order..TP.B bfs \-name '*.txt'Prints all the .txt files under the current directory..B *.txtis quoted to ensure the glob is processed by.B bfsrather than the shell..TP.BI "bfs \-name access_log \-L " /varFinds all files named.B access_logunder.IR /var ,following symbolic links..B bfsallows flags and paths to appear anywhere on the command line..TP.BI "bfs " ~ " \-not \-user $USER"Prints all files in your home directory not owned by you..TP.B bfs \-xtype lFinds broken symbolic links..TP.B bfs \-name config \-exclude \-name .gitFinds all files named.BR config ,skipping every.B .gitdirectory..TP.B bfs \-type f \-executable \-exec strip {} +Runs.BR strip (1)on all executable files it finds, passing it multiple files at a time..SH BUGShttps://github.com/tavianator/bfs/issues.SH AUTHORTavian Barnes <tavianator@tavianator.com>.PPhttps://tavianator.com/projects/bfs.html.SH SEE ALSO.BR find (1),.BR locate (1),.BR xargs (1)