brush

About

brush (Bo(u)rn(e) RUsty SHell) is a POSIX- and bash-compatible shell, implemented in Rust. It's built and tested on Linux and macOS, with experimental support on Windows. (Its Linux build is fully supported running on Windows via WSL.)

brush is functional for interactive use as a daily driver! It can execute most sh and bash scripts we've encountered. Known limitations are tracked with filed issues. Out of an abundance of caution, we wouldn't recommend using it yet in production scenarios in case it doesn't behave identically to your existing stable shell. (If you do find any behavioral differences, though, please report them with an issue!)

Contributions and feedback of all kinds are welcome! For more guidance, please consult our contribution guidelines. For more technical details, please consult the documentation in this repo.

This project was originally borne out of curiosity and a desire to learn. We're doing our best to keep that attitude :).

License

Available for use and distribution under the MIT license.

Try it out!

We don't publish binary releases of brush, but if you have a working rust toolchain installed you can simply run:

cargo install --locked brush-shell

This will install the most recently released version of brush from crates.io. Alternatively, for the latest and greatest bits, you can clone this repo and execute cargo run.

If you don't have rust installed, we recommend installing it via rustup.

(If you are interested in having a binary release, then please let us know in the 'Discussions' area of this project or by filing a feature request in 'Issues'.)

If you are a Nix user, you can also use the registered version.

nix run 'github:NixOS/nixpkgs/nixpkgs-unstable#brush' -- --version

Arch Linux users can install brush from the AUR with their AUR helper of choice, e.g.

paru -S brush

When you run brush, it should look exactly as bash would on your system since it processes .bashrc and other usual configuration. If you'd like to customize the look of brush to distinguish it from the other shells installed on your system, then you can also author a ~/.brushrc file.

Known limitations

There are some known gaps in compatibility. Most notably:

• Some set and shopt options. The set builtin is implemented, as is set -x and many frequently used set/shopt options, but a number aren't fully implemented. For example, set -e will execute but its semantics aren't applied across execution.

• Anything tagged with a TODO comment or where error::unimp() is used to return a "not implemented" error. These aren't all tracked with GitHub issues right now, but there's a number of these scattered throughout the code base. Some are indicative of missing functionality that may be straightforward to implement; others may be more complicated.

If you feel so inclined, we'd love contributions toward any of the above, with broadening test coverage, deeper compatibility evaluation, or really any other opportunities you can find to help us make this project better.

Testing strategy

This project is primarily tested by comparing its behavior with other existing shells, leveraging the latter as test oracles. The integration tests implemented in this repo include 550+ test cases run on both this shell and an oracle, comparing standard output and exit codes.

For more details, please consult the reference documentation on integration testing.

Credits

There's a long list of OSS crates whose shoulders this project rests on. Notably, the following crates are directly relied on for major portions of shell functionality:

• reedline - for readline-like input and interactive usage
• clap - command-line parsing, used both by the top-level brush CLI as well as built-in commands
• fancy-regex - relied on for everything regex
• tokio - async, well, everything
• nix rust crate - higher-level APIs for Unix/POSIX system APIs

For testing, performance benchmarking, and other important engineering support, we use and love:

• pprof-rs - for sampling-based CPU profiling
• criterion.rs - for statistics-based benchmarking
• bash-completion - for its completion test suite and general completion support!

Links: other shell implementations

There are a number of other POSIX-ish shells implemented in a non-C/C++ implementation language. Some inspirational examples include:

• nushell - modern Rust-implemented shell (which also provides the reedline crate we use!)
• rusty_bash
• mvdan/sh

We're sure there are plenty more; we're happy to include links to them as well.