diff options
Diffstat (limited to 'docs/bfs.1')
| -rw-r--r-- | docs/bfs.1 | 811 |
1 files changed, 811 insertions, 0 deletions
diff --git a/docs/bfs.1 b/docs/bfs.1 new file mode 100644 index 0000000..53a9831 --- /dev/null +++ b/docs/bfs.1 @@ -0,0 +1,811 @@ +.TH BFS 1 +.SH NAME +bfs \- breadth-first search for your files +.SH SYNOPSIS +.B bfs +.RB [ flags ...] +.RI [ paths ...] +.RB [ expression ...] +.PP +flags +.RB ( \-H / \-L / \-P +etc.), +.IR paths , +and +.B expressions +may be freely mixed in any order. +.SH DESCRIPTION +.B bfs +is a breadth-first version of the UNIX +.BR find (1) +command. +.PP +.B bfs +supports 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. +.PP +Each +.I path +specified 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. +.PP +Like +.BR find (1), +.B bfs +interprets its arguments as a short-circuiting Boolean expression. +For example, +.PP +.nf +.RS +.B bfs \\\( \-name '*.txt' \-or \-lname '*.txt' \\\\) \-and \-print +.RE +.fi +.PP +will print the all the paths that are either .txt files or symbolic links to .txt files. +.B \-and +is implied between two consecutive expressions, so this is equivalent: +.PP +.nf +.RS +.B bfs \\\( \-name '*.txt' \-or \-lname '*.txt' \\\\) \-print +.RE +.fi +.PP +Finally, +.B \-print +is implied if no actions are specified, so this too is equivalent: +.PP +.nf +.RS +.B bfs \-name '*.txt' \-or \-lname '*.txt' +.RE +.fi +.PP +Most options that take a numeric argument +.I N +will also accept +.I \-N +or +.IR +N . +.IR \-N +means "less than +.IR N ," +and +.I +N +means "greater than +.IR N ." +.SH FLAGS +.TP +.B \-H +Follow symbolic links on the command line, but not while searching. +.TP +.B \-L +Follow all symbolic links. +.TP +.B \-P +Never follow symbolic links (the default). +.TP +.B \-E +Use extended regular expressions (same as \fB\-regextype posix-extended\fR). +.TP +.B \-X +Filter out files with +.RB non- xargs (1)-safe +names. +.TP +.B \-d +Search in post-order (same as +.BR \-depth ). +.TP +.B \-s +Visit 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 \-x +Don't descend into other mount points (same as \fB\-xdev\fR). +.TP +\fB\-f \fIPATH\fR +Treat +.I PATH +as a path to search (useful if it begins with a dash). +.PP +.TP +\fB\-D \fIFLAG\fR +Turn on a debugging flag (see +.B \-D +.IR help ). +.PP +\fB\-O\fIN\fR +.RS +Enable optimization level +.I N +(default: +.IR 3 ). +.TP +.BI \-O 0 +Disable all optimizations. +.TP +.BI \-O 1 +Basic logical simplifications. +.TP +.BI \-O 2 +All +.BI \-O 1 +optimizations, plus dead code elimination and data flow analysis. +.TP +.BI \-O 3 +All +.BI \-O 2 +optimizations, plus re-order expressions to reduce expected cost. +.TP +\fB\-O\fI4\fR/\fB\-O\fIfast\fR +All 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 +.RS +Choose the search strategy. +.TP +.I bfs +Breadth-first search (the default). +.TP +.I dfs +Depth-first search. +Uses less memory than breadth-first search, but is typically slower to return relevant results. +.TP +.I 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 +.B \-S +.I bfs +consumes too much memory. +.TP +.I 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 +.B \-S +.IR ids . +.RE +.SH OPERATORS +.TP +\fB( \fIexpression \fB)\fR +Parentheses are used for grouping expressions together. +You'll probably have to write +.B \\\\( +.I expression +.B \\\\) +to avoid the parentheses being interpreted by the shell. +.PP +\fB! \fIexpression\fR +.br +\fB\-not \fIexpression\fR +.RS +The "not" operator: returns the negation of the truth value of the +.IR expression . +You may have to write \fB\\! \fIexpression\fR to avoid \fB!\fR being interpreted by the shell. +.RE +.PP +\fIexpression\fR \fIexpression\fR +.br +\fIexpression \fB\-a \fIexpression\fR +.br +\fIexpression \fB\-and \fIexpression\fR +.RS +Short-circuiting "and" operator: if the left-hand +.I expression +is +.BR true , +returns the right-hand +.IR expression ; +otherwise, returns +.BR false . +.RE +.PP +\fIexpression \fB\-o \fIexpression\fR +.br +\fIexpression \fB\-or \fIexpression\fR +.RS +Short-circuiting "or" operator: if the left-hand +.I expression +is +.BR false , +returns the right-hand +.IR expression ; +otherwise, returns +.BR true . +.RE +.TP +\fIexpression \fB, \fIexpression\fR +The "comma" operator: evaluates the left-hand +.I expression +but discards the result, returning the right-hand +.IR expression . +.SH SPECIAL FORMS +.TP +\fB\-exclude \fIexpression\fR +Exclude all paths matching the +.I expression +from the search. +This is more powerful than +.BR \-prune , +because it applies even when the expression wouldn't otherwise be evaluated, due to +.B \-depth +or +.B \-mindepth +for example. +Exclusions are always applied before other expressions, so it may be least confusing to put them first on the command line. +.SH OPTIONS +.PP +.B \-color +.br +.B \-nocolor +.RS +Turn colors on or off (default: +.B \-color +if outputting to a terminal, +.B \-nocolor +otherwise). +.RE +.TP +.B \-daystart +Measure time relative to the start of today. +.TP +.B \-depth +Search in post-order (descendents first). +.TP +.B \-follow +Follow all symbolic links (same as +.BR \-L ). +.TP +\fB\-files0\-from \fIFILE\fR +Treat the NUL ('\\0')-separated paths in +.I FILE +as starting points for the search. +Pass +.B \-files0\-from +.I \- +to read the paths from standard input. +.PP +\fB\-ignore_readdir_race\fR +.br +\fB\-noignore_readdir_race\fR +.RS +Whether to report an error if +.B bfs +detects that the file tree is modified during the search (default: +.BR \-noignore_readdir_race ). +.RE +.PP +\fB\-maxdepth \fIN\fR +.br +\fB\-mindepth \fIN\fR +.RS +Ignore files deeper/shallower than +.IR N . +.RE +.TP +.B \-mount +Don't descend into other mount points (same as +.B \-xdev +for now, but will skip mount points entirely in the future). +.TP +.B \-nohidden +Exclude hidden files and directories. +.TP +.B \-noleaf +Ignored; for compatibility with GNU find. +.TP +\fB\-regextype \fITYPE\fR +Use +.IR TYPE -flavored +regexes (default: +.IR posix-basic ; +see +.B \-regextype +.IR help ). +.TP +.B \-status +Display a status bar while searching. +.TP +.B \-unique +Skip any files that have already been seen. +Particularly useful along with +.BR \-L . +.PP +.B \-warn +.br +.B \-nowarn +.RS +Turn on or off warnings about the command line. +.RE +.TP +.B \-xdev +Don't descend into other mount points. +.SH TESTS +.TP +.B \-acl +Find 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 +.RS +Find files +.BR a ccessed/ B irthed/ c hanged/ m odified +.I N +minutes ago. +.RE +.PP +\fB\-anewer \fIFILE\fR +.br +\fB\-Bnewer \fIFILE\fR +.br +\fB\-cnewer \fIFILE\fR +.br +\fB\-mnewer \fIFILE\fR +.RS +Find files +.BR a ccessed/ B irthed/ c hanged/ m odified +more recently than +.I FILE +was modified. +.RE +.PP +\fB\-asince \fITIME\fR +.br +\fB\-Bsince \fITIME\fR +.br +\fB\-csince \fITIME\fR +.br +\fB\-msince \fITIME\fR +.RS +Find files +.BR a ccessed/ B irthed/ c hanged/ m odified +more recently than the ISO 8601-style timestamp +.IR TIME . +See +.BI \-newer XY +for 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 +.RS +Find files +.BR a ccessed/ B irthed/ c hanged/ m odified +.I N +days ago. +.RE +.TP +.B \-capable +Find files with POSIX.1e +.BR capabilities (7) +set. +.TP +\fB\-depth\fR [\fI\-+\fR]\fIN\fR +Find files with depth +.IR N . +.TP +.B \-empty +Find empty files/directories. +.PP +.B \-executable +.br +.B \-readable +.br +.B \-writable +.RS +Find files the current user can execute/read/write. +.RE +.PP +.B \-false +.br +.B \-true +.RS +Always false/true. +.RE +.TP +.B \-fstype TYPE +Find files on file systems with the given +.BR TYPE . +.PP +\fB\-gid\fR [\fI\-+\fR]\fIN\fR +.br +\fB\-uid\fR [\fI\-+\fR]\fIN\fR +.RS +Find files owned by group/user ID +.IR N . +.RE +.PP +\fB\-group \fINAME\fR +.br +\fB\-user \fINAME\fR +.RS +Find files owned by the group/user +.IR NAME . +.RE +.TP +.B \-hidden +Find hidden files (those beginning with +.IR . ). +.PP +\fB\-ilname \fIGLOB\fR +.br +\fB\-iname \fIGLOB\fR +.br +\fB\-ipath \fIGLOB\fR +.br +\fB\-iregex \fIREGEX\fR +.br +\fB\-iwholename \fIGLOB\fR +.RS +Case-insensitive versions of +.BR \-lname / \-name / \-path / \-regex / \-wholename . +.RE +.TP +\fB\-inum\fR [\fI\-+\fR]\fIN\fR +Find files with inode number +.IR N . +.TP +\fB\-links\fR [\fI\-+\fR]\fIN\fR +Find files with +.I N +hard links. +.TP +\fB\-lname \fIGLOB\fR +Find symbolic links whose target matches the +.IR GLOB . +.TP +\fB\-name \fIGLOB\fR +Find files whose name matches the +.IR GLOB . +.TP +\fB\-newer \fIFILE\fR +Find files newer than +.IR FILE . +.TP +\fB\-newer\fIXY \fIREFERENCE\fR +Find files whose +.I X +time is newer than the +.I Y +time of +.IR REFERENCE . +.I X +and +.I Y +can be any of +.RI [ aBcm ] +.RI ( a ccess/ B irth/ c hange/ m odification). +.I Y +may also be +.I t +to parse +.I REFERENCE +as an ISO 8601-style timestamp. For example: +.PP +.RS +1991-12-14 +.br +1991-12-14T03:00 +.br +1991-12-14T03:00-07:00 +.br +1991-12-14T10:00Z +.RE +.PP +.B \-nogroup +.br +.B \-nouser +.RS +Find files owned by nonexistent groups/users. +.RE +.PP +\fB\-path \fIGLOB\fR +.br +\fB\-wholename \fIGLOB\fR +.RS +Find files whose entire path matches the +.IR GLOB . +.RE +.TP +\fB\-perm\fR [\fI\-\fR]\fIMODE\fR +Find files with a matching mode. +.TP +\fB\-regex \fIREGEX\fR +Find files whose entire path matches the regular expression +.IR REGEX . +.TP +\fB\-samefile \fIFILE\fR +Find hard links to +.IR FILE . +.TP +\fB\-since \fITIME\fR +Find files modified since the ISO 8601-style timestamp +.IR TIME . +See +.BI \-newer XY +for examples of the timestamp format. +.TP +\fB\-size\fR [\fI\-+\fR]\fIN\fR[\fIcwbkMGTP\fR] +Find files with the given size, in 1-byte +.IR c haracters, +2-byte +.IR w ords, +512-byte +.IR b locks +(default), or +.IR k iB/ M iB/ G iB/ T iB/ P iB. +.TP +.B \-sparse +Find files that occupy fewer disk blocks than expected. +.TP +\fB\-type\fR [\fIbcdlpfswD\fR] +Find files of the given type. +Possible types are +.IR b lock +device, +.IR c haracter +device, +.IR d irectory, +symbolic +.IR l ink, +.IR p ipe, +regular +.IR f ile, +.IR s ocket, +.IR w hiteout, +and +.IR D oor. +.TP +\fB\-used\fR [\fI\-+\fR]\fIN\fR +Find files last accessed +.I N +days after they were changed. +.TP +.B \-xattr +Find files with extended attributes +.RB ( xattr (7)). +.TP +\fB\-xattrname\fR \fINAME\fR +Find files with the extended attribute +.IR NAME . +.TP +\fB\-xtype\fR [\fIbcdlpfswD\fR] +Find files of the given type, following links when +.B \-type +would not, and vice versa. +.SH ACTIONS +.PP +.B \-delete +.br +.B \-rm +.RS +Delete any found files (implies \fB-depth\fR). +.RE +.TP +\fB\-exec \fIcommand ... {} ;\fR +Execute a command. +.TP +\fB\-exec \fIcommand ... {} +\fR +Execute a command with multiple files at once. +.TP +\fB\-ok \fIcommand ... {} ;\fR +Prompt the user whether to execute a command. +.PP +\fB\-execdir \fIcommand ... {} ;\fR +.br +\fB\-execdir \fIcommand ... {} +\fR +.br +\fB\-okdir \fIcommand ... {} ;\fR +.RS +Like +.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 (0 if unspecified). +.PP +\fB\-fls \fIFILE\fR +.br +\fB\-fprint \fIFILE\fR +.br +\fB\-fprint0 \fIFILE\fR +.br +\fB\-fprintf \fIFILE FORMAT\fR +.RS +Like +.BR \-ls / \-print / \-print0 / \-printf , +but write to +.I FILE +instead of standard output. +.RE +.TP +.B \-ls +List files like +.B ls +.IR \-dils . +.TP +.B \-print +Print the path to the found file. +.TP +.B \-print0 +Like +.BR \-print , +but use the null character ('\\0') as a separator rather than newlines. +Useful in conjunction with +.B xargs +.IR \-0 . +.TP +\fB\-printf \fIFORMAT\fR +Print according to a format string (see +.BR find (1)). +These additional format directives are supported: +.RS +.TP +%w +The file's birth time, in the same format as %a/%c/%t. +.TP +.RI %W k +Field +.I k +of the file's birth time, in the same format as +.RI %A k /%C k /%T k . +.RE +.TP +.B \-printx +Like +.BR \-print , +but escape whitespace and quotation characters, to make the output safe for +.BR xargs (1). +Consider using +.B \-print0 +and +.B xargs +.I \-0 +instead. +.TP +.B \-prune +Don't descend into this directory. +.TP +.B \-quit +Quit immediately. +.TP +.B \-version +Print version information. +.TP +.B \-help +Print usage information. +.SH ENVIRONMENT +Certain environment variables affect the behavior of +.BR bfs . +.PP +.B LANG +.br +.B LC_* +.RS +Specifies the +.BR locale (7) +in use for various things. +.B 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 +.BR \-ok ) +will also be interpreted according to the current locale. +.RE +.PP +.B LS_COLORS +.br +.B BFS_COLORS +.RS +Controls the colors used when displaying file paths if +.B \-color +is enabled. +.B bfs +interprets +.B LS_COLORS +the same way GNU +.BR ls (1) +does (see +.BR dir_colors (5)). +.B BFS_COLORS +can be used to customize +.B bfs +without affecting other commands. +.RE +.TP +.B NO_COLOR +Causes +.B bfs +to default to +.B \-nocolor +if it is set (see https://no-color.org/). +.TP +.B PAGER +Specifies the pager used for +.B \-help +output. +Defaults to +.BR more (1). +.TP +.B POSIXLY_CORRECT +Makes +.B bfs +conform more strictly to the POSIX.1-2017 specification for +.BR find (1). +Currently this just disables warnings by default. +It does not disable +.BR bfs 's +various extensions to the base POSIX functionality. +.SH EXAMPLES +.TP +.B bfs +With no arguments, +.B bfs +prints 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 *.txt +is quoted to ensure the glob is processed by +.B bfs +rather than the shell. +.TP +\fBbfs \-name access_log \-L \fI/var\fR +Finds all files named +.B access_log +under +.IR /var , +following symbolic links. +.B bfs +allows flags and paths to appear anywhere on the command line. +.TP +\fBbfs \fI~ \fB\-not \-user $USER\fR +Prints all files in your home directory not owned by you. +.TP +.B bfs \-xtype l +Finds broken symbolic links. +.TP +.B bfs \-name config \-exclude \-name .git +Finds all files named +.BR config, +skipping every +.B .git +directory. +.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 BUGS +https://github.com/tavianator/bfs/issues +.SH AUTHOR +Tavian Barnes <tavianator@tavianator.com> +.PP +https://tavianator.com/projects/bfs.html +.SH SEE ALSO +.BR find (1), +.BR locate (1), +.BR xargs (1) |