summaryrefslogtreecommitdiffstats
path: root/bfs.1
diff options
context:
space:
mode:
Diffstat (limited to 'bfs.1')
-rw-r--r--bfs.1662
1 files changed, 662 insertions, 0 deletions
diff --git a/bfs.1 b/bfs.1
new file mode 100644
index 0000000..f49e505
--- /dev/null
+++ b/bfs.1
@@ -0,0 +1,662 @@
+.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 (see
+.B bfs-SPECIFIC FEATURES
+below).
+.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 POSIX find FEATURES
+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.
+.TP
+\fB! \fIexpression\fR
+The "not" operator: returns the negation of the truth value of the
+.IR expression .
+You may have to write
+.B \\\\!
+.I expression
+to avoid
+.B !
+being interpreted by the shell.
+.TP
+\fIexpression\fR [\fB\-a\fR] \fIexpression\fR
+Short-circuiting "and" operator: if the left-hand
+.I expression
+is
+.BR true ,
+returns the right-hand
+.IR expression ;
+otherwise, returns
+.BR false .
+.TP
+\fIexpression \fB\-o \fIexpression\fR
+Short-circuiting "or" operator: if the left-hand
+.I expression
+is
+.BR false ,
+returns the right-hand
+.IR expression ;
+otherwise, returns
+.BR true .
+.LP
+Flags:
+.TP
+.B \-H
+Follow symbolic links on the command line, but not while searching.
+.TP
+.B \-L
+Follow all symbolic links.
+.LP
+Options:
+.TP
+.B \-depth
+Search in post-order (descendents first).
+.TP
+.B \-xdev
+Don't descend into other mount points.
+.LP
+Tests:
+.PP
+\fB\-atime\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/ c hanged/ m odified
+.I N
+days ago.
+.RE
+.PP
+.B \-group NAME
+.br
+.B \-user NAME
+.RS
+Find files owned by the group/user
+.BR NAME .
+.RE
+.TP
+\fB\-links\fR [\fI\-+\fR]\fIN\fR
+Find files with
+.I N
+hard links.
+.TP
+\fB\-name \fIGLOB\fR
+Find files whose name matches the
+.IR GLOB .
+.TP
+\fB\-path \fIGLOB\fR
+Find files whose entire path matches the
+.IR GLOB .
+.TP
+\fB\-newer \fIFILE\fR
+Find files newer than
+.IR FILE .
+.TP
+\fB\-perm\fR [\fI\-\fR]\fIMODE\fR
+Find files with a matching mode.
+.TP
+\fB\-type\fR [\fIbcdlpfs\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,
+and
+.IR s ocket.
+.TP
+\fB\-size\fR [\fI\-+\fR]\fIN\fR[\fIc\fR]
+Find files with the given size.
+The default unit is 512-byte blocks;
+.I c
+counts
+.IR c haracters/bytes
+instead.
+.LP
+Actions:
+.TP
+.B \-prune
+Don't descend into this directory.
+.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.
+.TP
+.B \-print
+Print the path to the found file.
+.SH GNU find FEATURES
+Operators:
+.TP
+\fB\-not \fIexpression\fR
+Same as
+.B !
+.IR expression .
+.TP
+\fIexpression \fB\-and \fIexpression\fR
+Same as
+.I expression
+.B \-a
+.IR expression .
+.TP
+\fIexpression \fB\-or \fIexpression\fR
+Same as
+.I expression
+.B \-o
+.IR expression .
+.TP
+\fIexpression \fB, \fIexpression\fR
+The "comma" operator: evaluates the left-hand
+.I expression
+but discards the result, returning the right-hand
+.IR expression .
+.LP
+Flags:
+.TP
+.B \-P
+Never follow symbolic links (the default).
+.TP
+\fB\-D \fIFLAG\fR
+Turn on a debugging flag (see
+.B \-D
+.IR help ).
+.TP
+\fB\-O\fIN\fR
+Enable optimization level
+.I N
+(default: 3; interpreted differently than GNU find -- see below).
+.LP
+Options:
+.TP
+.B \-d
+Search in post-order (same as
+.BR \-depth ).
+.TP
+.B \-daystart
+Measure time relative to the start of today.
+.TP
+.B \-follow
+Follow all symbolic links (same as
+.BR \-L ).
+.LP
+.B \-ignore_readdir_race
+.br
+.B \-noignore_readdir_race
+.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
+.BR \-xdev ).
+.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 ).
+.LP
+.B \-warn
+.br
+.B \-nowarn
+.RS
+Turn on or off warnings about the command line.
+.RE
+.PP
+Tests:
+.PP
+\fB\-amin\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/ c hanged/ m odified
+.I N
+minutes ago.
+.RE
+.PP
+\fB\-anewer \fIFILE\fR
+.br
+\fB\-cnewer \fIFILE\fR
+.br
+\fB\-mnewer \fIFILE\fR
+.RS
+Find files
+.BR a ccessed/ c hanged/ m odified
+more recently than
+.I FILE
+was modified.
+.RE
+.TP
+.B \-empty
+Find empty files/directories.
+.LP
+.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 .
+.LP
+\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
+.TP
+\fB\-inum\fR [\fI\-+\fR]\fIN\fR
+Find files with inode number
+.IR N .
+.TP
+\fB\-lname \fIGLOB\fR
+Find symbolic links whose target matches the
+.IR GLOB .
+.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 [ acm ]
+.RI ( a ccess/ c hange/ m odification).
+.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\-size\fR [\fI\-+\fR]\fIN\fR[\fIcwbkMG\fR]
+1-byte
+.IR c haracters,
+2-byte
+.IR w ords,
+512-byte
+.IR b locks,
+and
+.IR k iB/ M iB/ G iB.
+.TP
+\fB\-type\fR [\fIbcdlpfsD\fR]
+The
+.IR D oor
+file type is also supported on platforms that have it (Solaris).
+.TP
+\fB\-used\fR [\fI\-+\fR]\fIN\fR
+Find files last accessed
+.I N
+days after they were changed.
+.TP
+\fB\-wholename \fIGLOB\fR
+Find files whose entire path matches the
+.I GLOB
+(same as
+.BR \-path ).
+.LP
+\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\-xtype\fR [\fIbcdlpfsD\fR]
+Find files of the given type, following links when
+.B \-type
+would not, and vice versa.
+.LP
+Actions:
+.TP
+.B \-delete
+Delete any found files (implies \fB-depth\fR).
+.LP
+\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
+.B \-ls
+List files like
+.B ls
+.IR \-dils .
+.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)).
+.LP
+\fB\-fls \fIFILE\fR
+.br
+\fB\-fprint \fIFILE\fR
+.br
+\fB\-fprint0 \fIFILE\fR
+.br
+\fB\-fprintf \fIFORMAT FILE\fR
+.RS
+Like
+.BR \-ls / \-print / \-print0 / \-printf ,
+but write to
+.I FILE
+instead of standard output.
+.RE
+.TP
+.B \-quit
+Quit immediately.
+.TP
+.B \-version
+Print version information.
+.TP
+.B \-help
+Print usage information.
+.SH BSD find FEATURES
+Flags:
+.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 \-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).
+.LP
+Tests:
+.TP
+\fB\-depth\fR [\fI\-+\fR]\fIN\fR
+Find files with depth
+.IR N .
+.LP
+.B \-gid NAME
+.br
+.B \-uid NAME
+.RS
+Group/user names are supported in addition to numeric IDs.
+.RE
+.TP
+\fB\-size\fR [\fI\-+\fR]\fIN\fR[\fIcwbkMGTP\fR]
+Units of
+.IR T iB/ P iB
+are additionally supported.
+.TP
+.B \-sparse
+Find files that occupy fewer disk blocks than expected.
+.LP
+Actions:
+.TP
+\fB\-exit\fR [\fISTATUS\fR]
+Exit immediately with the given status (0 if unspecified).
+.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 \-rm
+Delete any found files (same as
+.BR \-delete ;
+implies
+.BR \-depth ).
+.SH bfs-SPECIFIC FEATURES
+Flags:
+.TP
+\fB\-O\fI0\fR
+Disable all optimizations.
+.TP
+\fB\-O\fI1\fR
+Basic logical simplifications.
+.TP
+\fB\-O\fI2\fR
+All
+.BI \-O 1
+optimizations, plus dead code elimination and data flow analysis.
+.TP
+\fB\-O\fI3\fR
+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.
+.LP
+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
+.PP
+Tests:
+.TP
+.B \-hidden
+Match hidden files (those beginning with
+.IR . ).
+.LP
+Actions:
+.TP
+.B \-nohidden
+Filter out hidden files and directories.
+.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 .git \-prune \-false \-o \-name config
+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://github.com/tavianator/bfs
+.SH SEE ALSO
+.BR find (1),
+.BR locate (1),
+.BR xargs (1)