summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorTavian Barnes <tavianator@tavianator.com>2022-02-22 11:36:16 -0500
committerTavian Barnes <tavianator@tavianator.com>2022-02-22 11:37:31 -0500
commit1d5c7a546565b426d1358944163107a13ac0b931 (patch)
treece066d659bc7455b2b0da75b70edc78a95cc0e1d
parentccef0bb7171f90d572e47e845b6f728073336770 (diff)
downloadbfs-1d5c7a546565b426d1358944163107a13ac0b931.tar.xz
README: Reformat with details blocks to make it more easily skimmable
And add some extra information about bfs-specific features, and installing dependencies.
-rw-r--r--README.md141
1 files changed, 111 insertions, 30 deletions
diff --git a/README.md b/README.md
index d613834..6db8a31 100644
--- a/README.md
+++ b/README.md
@@ -22,10 +22,12 @@ It is otherwise compatible with many versions of `find`, including
If you're not familiar with `find`, the [GNU find manual](https://www.gnu.org/software/findutils/manual/html_mono/find.html) provides a good introduction.
-Breadth vs. depth
------------------
+Features
+--------
+
+<details>
+<summary><code>bfs</code> operates breadth-first, which typically finds the file(s) you're looking for faster.</summary>
-The advantage of breadth-first over depth first search is that it usually finds the file(s) you're looking for faster.
Imagine the following directory tree:
<pre>
@@ -69,46 +71,78 @@ haystack/deep/1/2/3
haystack/deep/1/2/3/4
...
</pre>
+</details>
+<details>
+<summary><code>bfs</code> tries to be easier to use than <code>find</code>, while remaining compatible.</summary>
-Easy
-----
-
-`bfs` tries to be easier to use than `find`, while remaining compatible.
For example, `bfs` is less picky about where you put its arguments:
<pre>
-$ <strong>find</strong> -L -name 'needle' <em>haystack</em>
-find: paths must precede expression: haystack
-$ <strong>bfs</strong> -L -name 'needle' <em>haystack</em>
-<strong>haystack/needle</strong>
-
-$ <strong>find</strong> <em>haystack</em> -L -name 'needle'
-find: unknown predicate `-L'
-$ <strong>bfs</strong> <em>haystack</em> -L -name 'needle'
-<strong>haystack/needle</strong>
-
-$ <strong>find</strong> -L <em>haystack</em> -name 'needle'
-<strong>haystack/needle</strong>
-$ <strong>bfs</strong> -L <em>haystack</em> -name 'needle'
-<strong>haystack/needle</strong>
+$ <strong>bfs</strong> -L -name 'needle' <em>haystack</em> │ $ <strong>find</strong> -L -name 'needle' <em>haystack</em>
+<strong>haystack/needle</strong> │ find: paths must precede expression: haystack
+ │
+$ <strong>bfs</strong> <em>haystack</em> -L -name 'needle' │ $ <strong>find</strong> <em>haystack</em> -L -name 'needle'
+<strong>haystack/needle</strong> │ find: unknown predicate `-L'
+ │
+$ <strong>bfs</strong> -L <em>haystack</em> -name 'needle' │ $ <strong>find</strong> -L <em>haystack</em> -name 'needle'
+<strong>haystack/needle</strong> │ <strong>haystack/needle</strong>
</pre>
+</details>
+
+<details>
+<summary><code>bfs</code> adds some options that make common tasks easier.</summary>
-`bfs` also adds some extra options that make some common tasks easier.
-Compare
+### `-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
-vs.
+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`.
+
+---
-Try it!
--------
+### `-unique`
-`bfs` may already be packaged for your distribution of choice.
-For example:
+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.
+</details>
+
+
+Installation
+------------
+
+<details>
+<summary><code>bfs</code> may already be packaged for your operating system.</summary>
<pre>
<strong>Alpine Linux</strong>
@@ -132,8 +166,55 @@ For example:
<strong>Homebrew</strong>
$ brew install tavianator/tap/bfs
</pre>
+</details>
+
+<details>
+<summary>To build <code>bfs</code> from source, you may need to install some dependencies.</summary>
+
+The only absolute requirements for building `bfs` are a C compiler and GNU make.
+These are installed by default on many systems, and easy to install on most others.
+Refer to your operating system's documentation on building software.
+
+`bfs` also depends on some system libraries for some of its features.
+These dependencies are optional, and can be turned off at build time if necessary by setting the appropriate variable to the empty string (e.g. `make WITH_ONIGURUMA=`).
+
+| Dependency | Platforms | `make` flag |
+|-------------------------------------------------------|------------|------------------|
+| [acl](https://savannah.nongnu.org/projects/acl) | Linux only | `WITH_ACL` |
+| [attr](https://savannah.nongnu.org/projects/attr) | Linux only | `WITH_ATTR` |
+| [libcap](https://sites.google.com/site/fullycapable/) | Linux only | `WITH_LIBCAP` |
+| [Oniguruma](https://github.com/kkos/oniguruma) | All | `WITH_ONIGURUMA` |
+
+Here's how to install them on some common platforms:
+
+<pre>
+<strong>Alpine Linux</strong>
+# apk add acl-dev attr-dev libcap-dev oniguruma-dev
+
+<strong>Arch Linux</strong>
+# pacman -S acl attr libcap oniguruma
+
+<strong>Debian/Ubuntu</strong>
+# apt install acl libacl1-dev attr libattr1-dev libcap2-bin libcap-dev libonig-dev
+
+<strong>NixOS</strong>
+# nix-env -i acl attr libcap oniguruma
+
+<strong>Void Linux</strong>
+# xbps-install -S acl-devel attr-devel libcap-devel oniguruma-devel
+
+<strong>FreeBSD</strong>
+# pkg install oniguruma
+
+<strong>MacPorts</strong>
+# port install oniguruma6
+
+<strong>Homebrew</strong>
+$ brew install oniguruma
+</pre>
+</details>
-To install `bfs` from source, download one of the [releases](https://github.com/tavianator/bfs/releases) or clone the [git repo](https://github.com/tavianator/bfs).
+Once the dependencies are installed, download one of the [releases](https://github.com/tavianator/bfs/releases) or clone the [git repo](https://github.com/tavianator/bfs).
Then run
$ make
@@ -149,4 +230,4 @@ If you're interested in speed, you may want to build the release version instead
Finally, if you want to install it globally, run
- $ sudo make install
+ # make install