zbr

zbr is a tool for managing auto-expanding abbreviations for ZSH. With the default configuration, typing gcoSpace into ZSH results in git checkout ; the abbreviation is expanded in place. Don't want an abbreviation to expand? Just use CtrlSpace instead.

Quoting from the README of zsh-abbr:

Why? Like aliases, abbreviations save keystrokes. Unlike aliases, abbreviations can leave you with a transparently understandable command history ready for using on a different computer or sharing with a colleague. And where aliases can let you forget the full command, abbreviations may help you learn the full command even as you type the shortened version.

Features

Extraction

zbr supports extracting abbreviations from command-line tools. Running

zbr extract cargo conf/cargo.toml

generates a configuration file that contains all of the following abbreviations and more!

cg --> cargo
cg -e --> cargo --explain
cg -f --> cargo --frozen
cg -h --> cargo --help
...
cga --> cargo add
cgb --> cargo build
cgbe --> cargo bench
cgc --> cargo check
...
cargo -e --> cargo --explain
cargo -f --> cargo --frozen
cargo -h --> cargo --help
...
cargo a --> cargo add
cargo b --> cargo build
cargo be --> cargo bench
cargo c --> cargo check
...

Discoverability

zbr will also show you abbreviations as you type, typing git s will display applicable abbreviations just below the command prompt:

git s --> git status
git see --> git send-email
git sep --> git send-pack
...

Smart abbreviations

zbr detects the build system of the project you're working on, and creates the abbreviations b for "build", r for "run", and t for "test". For example, when working in a directory with a Cargo.toml, zbr will use the abbreviations

b --> cargo build
r --> cargo run
t --> cargo test

but when working on a Haskell project, cargo would be replace by cabal.

Unique prefixes for subcommands

In addition to pithy abbreviations like gsu --> git submodule, zbr abbreviates all uniquely identifying prefixes of subcommands. For example, it will automatically abbreviate

git sub --> git submodule
git subm --> git submodule
git submo --> git submodule

and so on, meaning you can just press Space at any point to expand to the full subcommand name.

zsh-abbr is quite similar, but doesn't support extracting abbreviations nor contextual abbreviations.
zabrze is quite similar, but doesn't support extracting abbreviations

Contributing

Thank you for your interest in zbr! We welcome and appreciate all kinds of contributions. Please feel free to file and issue or open a pull request.

You may want to take a look at:

If you have questions, please ask them on the discussions page!

Installation

Pre-compiled binaries

Pre-compiled binaries are available on the releases page.

Fetching binaries with cURL

You can download binaries with curl like so (replace X.Y.Z with a real version number and TARGET with your OS):

curl -sSL https://github.com/langston-barrett/zbr/releases/download/vX.Y.Z/zbr_TARGET -o zbr

Build from source

To install from source, you'll need to install Rust and Cargo. Follow the instructions on the Rust installation page.

From the latest unreleased version on Github

To build and install the very latest unreleased version, run:

cargo install --git https://github.com/langston-barrett/zbr.git zbr

From a local checkout

See the developer's guide.

Usage

To use zbr, first create a configuration file. There is an example at conf/conf.toml. Then, add the following to your zshrc:

eval "$(zbr init path/to/your/conf.toml)"

Developer's guide

Build

To install from source, you'll need to install Rust and Cargo. Follow the instructions on the Rust installation page. Then, get the source:

git clone https://github.com/langston-barrett/zbr
cd zbr

Finally, build everything:

cargo build --release

You can find binaries in target/release. Run tests with cargo test.

Docs

HTML documentation can be built with mdBook:

cd doc
mdbook build

Format

All code should be formatted with rustfmt. You can install rustfmt with rustup like so:

rustup component add rustfmt

and then run it like this:

cargo fmt

Lint

All code should pass Clippy. You can install Clippy with rustup like so:

rustup component add clippy

and then run it like this:

cargo clippy --workspace -- --deny warnings

Profile

TODO

Warnings

Certain warnings are disallowed in the CI build. You can reproduce the behavior of the CI build by running cargo check, cargo build, or cargo test like so:

env RUSTFLAGS="@$PWD/rustc-flags" cargo check

Using a flag file for this purpose achieves several objectives:

It frictionlessly allows code with warnings during local development
It makes it easy to reproduce the CI build process locally
It makes it easy to maintain the list of warnings
It maintains forward-compatibility with future rustc warnings
It ensures the flags are consistent across all crates in the project

This flag file rejects all rustc warnings by default, as well as a subset of allowed-by-default lints. The goal is to balance high-quality, maintainable code with not annoying developers.

To allow a lint in one spot, use:

#![allow(unused)]
fn main() {
#[allow(name_of_lint)]
}

To enable these warnings on a semi-permanent basis, create a [Cargo configuration file][cargo-conf]:

mkdir .cargo
printf "[build]\nrustflags = [\"@${PWD}/rustc-flags\"]\n" > .cargo/config.toml

Keyboard shortcuts

zbr