From aa6797db463b5143c5ca05bb5e90b05d2f72122a Mon Sep 17 00:00:00 2001
From: Tavian Barnes <tavianator@tavianator.com>
Date: Tue, 19 Apr 2022 11:30:47 -0400
Subject: docs: Move some documentation into a subfolder

---
 bfs.1 | 811 ------------------------------------------------------------------
 1 file changed, 811 deletions(-)
 delete mode 100644 bfs.1

(limited to 'bfs.1')

diff --git a/bfs.1 b/bfs.1
deleted file mode 100644
index 53a9831..0000000
--- a/bfs.1
+++ /dev/null
@@ -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)
-- 
cgit v1.2.3