diff options
Diffstat (limited to 'bfs.1')
| -rw-r--r-- | bfs.1 | 811 |
1 files changed, 0 insertions, 811 deletions
@@ -1,811 +0,0 @@ -.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) |