docs: Move some documentation into a subfolder

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)