diff options
| -rw-r--r-- | README.md | 54 | ||||
| -rw-r--r-- | docs/USAGE.md | 161 |
2 files changed, 175 insertions, 40 deletions
@@ -12,9 +12,10 @@ [ **[Features](#features)** ]  [ **[Installation](#installation)** ]  -[ **[Changelog](/docs/CHANGELOG.md)** ]  +[ **[Usage](/docs/USAGE.md)** ]  [ **[Building](/docs/BUILDING.md)** ]  -[ **[Hacking](/docs/HACKING.md)** ] +[ **[Hacking](/docs/HACKING.md)** ]  +[ **[Changelog](/docs/CHANGELOG.md)** ] <img src="https://tavianator.github.io/bfs/animation.svg" alt="Screenshot"> <p></p> @@ -126,7 +127,7 @@ $ bfs -nam needle <strong>bfs: error:</strong> Unknown argument; did you mean <strong>-name</strong>? </pre> -`bfs` also includes a powerful static analysis to identify likely mistakes: +`bfs` also includes a powerful static analysis to help catch mistakes: <pre> $ bfs -print -name 'needle' @@ -142,48 +143,21 @@ $ bfs -print -name 'needle' <p></p> </summary> -### `-exclude` +For example, the `-exclude` operator skips over entire subtrees whenever an expression matches. +`-exclude` is both more powerful and easier to use than the standard `-prune` action; compare -The `-exclude` operator skips an entire subtree whenever an expression matches. -For example, `-exclude -name .git` will exclude any files or directories named `.git` from the search results. -`-exclude` is easier to use than the standard `-prune` action; compare - - bfs -name config -exclude -name .git +<pre> +$ bfs -name config <strong>-exclude -name .git</strong> +</pre> to the equivalent - find ! \( -name .git -prune \) -name config - -Unlike `-prune`, `-exclude` even works in combination with `-depth`/`-delete`. - ---- - -### `-hidden`/`-nohidden` - -`-hidden` matches "hidden" files (dotfiles). -`bfs -hidden` is effectively shorthand for - - find \( -name '.*' -not -name . -not -name .. \) - -`-nohidden` is equivalent to `-exclude -hidden`. - ---- - -### `-unique` - -This option ensures that `bfs` only visits each file once, even if it's reachable through multiple hard or symbolic links. -It's particularly useful when following symbolic links (`-L`). - ---- - -### `-color`/`-nocolor` - -When printing to a terminal, `bfs` automatically colors paths like GNU `ls`, according to the `LS_COLORS` environment variable. -The `-color` and `-nocolor` options override the automatic behavior, which may be handy when you want to preserve colors through a pipe: - - bfs -color | less -R +<pre> +$ find <strong>! \( -name .git -prune \)</strong> -name config +</pre> -If the [`NO_COLOR`](https://no-color.org/) environment variable is set, colors will be disabled by default. +As an additional shorthand, `-nohidden` skips over all hidden files and directories. +See the [usage documentation](/docs/USAGE.md#extensions) for more about the extensions provided by `bfs`. </details> diff --git a/docs/USAGE.md b/docs/USAGE.md new file mode 100644 index 0000000..9f76f16 --- /dev/null +++ b/docs/USAGE.md @@ -0,0 +1,161 @@ +Using `bfs` +=========== + +`bfs` has the same command line syntax as `find`, and almost any `find` command that works with a major `find` implementation will also work with `bfs`. +When invoked with no arguments, `bfs` will list everything under the current directory recursively, breadth-first: + +```console +$ bfs +. +./LICENSE +./Makefile +./README.md +./completions +./docs +./src +./tests.sh +./tests +./completions/bfs.bash +./completions/bfs.zsh +./docs/BUILDING.md +./docs/CHANGELOG.md +./docs/HACKING.md +./docs/USAGE.md +./docs/bfs.1 +./src/bfs.h +... +``` + + +Paths +----- + +Arguments that don't begin with `-` are treated as paths to search. +If one or more paths are specified, they are used instead of the current directory: + +```console +$ bfs /usr/bin /usr/lib +/usr/bin +/usr/lib +/usr/bin/bfs +... +/usr/lib/libc.so +... +``` + + +Expressions +----------- + +Arguments that start with `-` form an *expression* which `bfs` evaluates to filter the matched files, and to do things with the files that match. +The most common expression is probably `-name`, which matches filenames against a glob pattern: + +```console +$ bfs -name '*.md' +./README.md +./docs/BUILDING.md +./docs/CHANGELOG.md +./docs/HACKING.md +./docs/USAGE.md +``` + +### Operators + +When you put multiple expressions next to each other, both of them must match: + +```console +$ bfs -name '*.md' -name '*ING*' +./docs/BUILDING.md +./docs/HACKING.md +``` + +This works because the expressions are implicitly combined with *logical and*. +You could be explicit by writing + +```console +$ bfs -name '*.md' -and -name '*ING'` +``` + +There are other operators like `-or`: + +```console +$ bfs -name '*.md' -or -name '*.sh' +./README.md +./tests.sh +./tests/find-color.sh +./tests/ls-color.sh +./tests/remove-sibling.sh +./tests/sort-args.sh +./docs/CHANGELOG.md +./docs/HACKING.md +./docs/BUILDING.md +./docs/USAGE.md +``` + +and `-not`: + +```console +$ bfs -name '*.md' -and -not -name '*ING*' +./README.md +./docs/CHANGELOG.md +./docs/USAGE.md +``` + +### Actions + +Every `bfs` expression returns either `true` or `false`. +For expressions like `-name`, that's all they do. +But some expressions, called *actions*, have other side effects. + +If no actions are included in the expression, `bfs` adds the `-print` action automatically, which is why the above examples actually print any output. +The default `-print` is supressed if any actions are given explicitly. +Available actions include printing with alternate formats (`-ls`, `-printf`, etc.), executing commands (`-exec`, `-execdir`, etc.), deleting files (`-delete`), and stopping the search (`-quit`, `-exit`). + + +Extensions +---------- + +`bfs` implements a few extensions not found in other `find` implementations. + +### `-exclude` + +The `-exclude` operator skips an entire subtree whenever an expression matches. +For example, `-exclude -name .git` will exclude any files or directories named `.git` from the search results. +`-exclude` is easier to use than the standard `-prune` action; compare + + bfs -name config -exclude -name .git + +to the equivalent + + find ! \( -name .git -prune \) -name config + +Unlike `-prune`, `-exclude` even works in combination with `-depth`/`-delete`. + +--- + +### `-hidden`/`-nohidden` + +`-hidden` matches "hidden" files (dotfiles). +`bfs -hidden` is effectively shorthand for + + find \( -name '.*' -not -name . -not -name .. \) + +`-nohidden` is equivalent to `-exclude -hidden`. + +--- + +### `-unique` + +This option ensures that `bfs` only visits each file once, even if it's reachable through multiple hard or symbolic links. +It's particularly useful when following symbolic links (`-L`). + +--- + +### `-color`/`-nocolor` + +When printing to a terminal, `bfs` automatically colors paths like GNU `ls`, according to the `LS_COLORS` environment variable. +The `-color` and `-nocolor` options override the automatic behavior, which may be handy when you want to preserve colors through a pipe: + + bfs -color | less -R + +If the [`NO_COLOR`](https://no-color.org/) environment variable is set, colors will be disabled by default. |