From 1d5c7a546565b426d1358944163107a13ac0b931 Mon Sep 17 00:00:00 2001 From: Tavian Barnes Date: Tue, 22 Feb 2022 11:36:16 -0500 Subject: README: Reformat with details blocks to make it more easily skimmable And add some extra information about bfs-specific features, and installing dependencies. --- README.md | 141 +++++++++++++++++++++++++++++++++++++++++++++++++------------- 1 file 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 +-------- + +
+bfs operates breadth-first, which typically finds the file(s) you're looking for faster. -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: 
@@ -69,46 +71,78 @@ haystack/deep/1/2/3
 haystack/deep/1/2/3/4
 ...
+
+
+bfs tries to be easier to use than find, while remaining compatible. -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: 
-$ find -L -name 'needle' haystack
-find: paths must precede expression: haystack
-$ bfs -L -name 'needle' haystack
-haystack/needle
-
-$ find haystack -L -name 'needle'
-find: unknown predicate `-L'
-$ bfs haystack -L -name 'needle'
-haystack/needle
-
-$ find -L haystack -name 'needle'
-haystack/needle
-$ bfs -L haystack -name 'needle'
-haystack/needle
+$ bfs -L -name 'needle' haystack    │ $ find -L -name 'needle' haystack
+haystack/needle                     │ find: paths must precede expression: haystack
+                                    │
+$ bfs haystack -L -name 'needle'    │ $ find haystack -L -name 'needle'
+haystack/needle                     │ find: unknown predicate `-L'
+                                    │
+$ bfs -L haystack -name 'needle'    │ $ find -L haystack -name 'needle'
+haystack/needle                     │ haystack/needle
+
+ +
+bfs adds some options that make common tasks easier. -`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. +
+ + +Installation +------------ + +
+bfs may already be packaged for your operating system. 
 Alpine Linux
@@ -132,8 +166,55 @@ For example:
 Homebrew
 $ brew install tavianator/tap/bfs
+
+ +
+To build bfs from source, you may need to install some dependencies. + +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: + +
+Alpine Linux
+# apk add acl-dev attr-dev libcap-dev oniguruma-dev
+
+Arch Linux
+# pacman -S acl attr libcap oniguruma
+
+Debian/Ubuntu
+# apt install acl libacl1-dev attr libattr1-dev libcap2-bin libcap-dev libonig-dev
+
+NixOS
+# nix-env -i acl attr libcap oniguruma
+
+Void Linux
+# xbps-install -S acl-devel attr-devel libcap-devel oniguruma-devel
+
+FreeBSD
+# pkg install oniguruma
+
+MacPorts
+# port install oniguruma6
+
+Homebrew
+$ brew install oniguruma
+
+
-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 -- cgit v1.2.3