montana / bfs

A breadth-first version of the UNIX find command

bfs

Breadth-first search for your files.

bfs is a variant of the UNIX find command that operates breadth-first rather than depth-first. It is otherwise intended to be compatible with many versions of find, including

• POSIX find
• GNU find
• {Free,Open,Net}BSD find
• macOS find

If you're not familiar with find, the GNU find manual provides a good introduction.

Breadth vs. depth

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:

haystack
├── deep
│   └── 1
│       └── 2
│           └── 3
│               └── 4
│                   └── ...
└── shallow
    └── needle

find will explore the entire deep directory tree before it ever gets to the shallow one that contains what you're looking for.

$ find haystack
haystack
haystack/deep
haystack/deep/1
haystack/deep/1/2
haystack/deep/1/2/3
haystack/deep/1/2/3/4
...
haystack/shallow
haystack/shallow/needle

On the other hand, bfs lists files from shallowest to deepest, so you never have to wait for it to explore an entire unrelated subtree.

$ bfs haystack
haystack
haystack/deep
haystack/shallow
haystack/deep/1
haystack/shallow/needle
haystack/deep/1/2
haystack/deep/1/2/3
haystack/deep/1/2/3/4
...

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 also adds some extra options that make some common tasks easier. Compare bfs -nohidden to

find -name '.?*' -prune -o -print

Pretty

When bfs detects that its output is a terminal, it automatically colors its output with the same colors ls uses. This makes it easier to identify relevant files at a glance.

Try it!

To get bfs, download one of the releases or clone the git repo. Then run

$ make

This will build the bfs binary in the current directory. You can test it out:

$ ./bfs -nohidden

If you're interested in speed, you may want to build the release version instead:

$ make clean
$ make release

Finally, if you want to install it globally, run

$ sudo make install

Alternatively, bfs may already be packaged for your distribution of choice:

For example:

# apt install bfs                  # Debian/Ubuntu
# brew install tavianator/tap/bfs  # macOS Homebrew