• BASH version 4

• BASH version 3 (partial compatibility, some functions are disabled)

• ZSH – as of recent update, Bashmatic is almost 100% compatible with ZSH.

Not Supported

• FISH (although you could use Bashmatic via bin/bashmatic script helper, or its executables)

First, make sure that you have Curl installed, run which curl to see. Then copy/paste this command into your Terminal.

[arrow down]

You can pass additional flags to the bashmatic-install function, including: * -v or --verbose for displaying additional output, or the opposite: * -q or --quiet for no output * If you prefer to install Bashmatic in a non-standard location (the default is ~/.bashmatic), you can use the -H PATH flag

For instance, here is a verbose installation with a custom destination:

Here is the complete list of options accepted by the installer:

When you run bash -c "$(curl -fsSL https://bashmatic.re1.re); bashmatic-install", the following typically happens:

• curl downloads the bin/bashmatic-install script and passes it to the built-in BASH for evaluation.

• Once evaluated, function bashmatic-install is invoked, which actually performs the installation.

  • This is the function that accepts the above listed arguments.

• The script may ask for your password to enable sudo access - this may be required on OS-X to install XCode Developer tools (which include git)

• If your version of BASH is 3 or older, the script will download and build from sources version 5 of BASH, and install it into /usr/local/bin/bash. SUDO may be required for this step.

• On OS-X the script will install Homebrew on OS-X, if not already there.

  • Once Brew is installed, brew packages coreutils and gnu-sed are installed, as both are required and are relied upon by Bashmatic.

• The script will then attempt to git clone the bashmatic repo into the Bashmatic home folder, or - if it already exists - it will git pull latest changes.

• Finally, the script will check your bash dot files, and will add the hook to load Bashmatic from either ~/.bashrc or ~/.bash_profile.

Restart your shell, and make sure that when you type bashmatic.version in the command line (and press Enter) you see the version number printed like so:

If you get an error, perhaps Bashmatic® did not properly install.

Next, to discover the breadth of available functions, type the following command to see all imported shell functions:

To install Bashmatic manually, follow these steps (feel free to change BASHMATIC_HOME if you like):

You can always reload Bashmatic® with bashmatic.reload function.

Makefile is provided as a convenience for running most common tasks and to simplify running some more complex tasks that require remembering many arguments, such as make setup, for example.

You might want to use the Makefile for several reasons:

• To run your local computer setup for software development:

  make setup

  This runs bin/dev-setup script with the following actions: dev, cpp, fonts, gnu, go, java, js, load-balancing, postgres, ruby

• To install Bashmatic with

  make install

Or, if you plan on contributing to the framework:

• You can run the test suite with:

  make test -B

• To update function index, re-generate the latest PDFs of README, USAGE or the CHANGELOG files:

  make update

Bashmatic comes with a Dockerfile that can be used to run tests, validate functionality under linux, or to experiment.

Run make docker-build to create an docker image bashmatic:latest.

Run make docker-run-bash (or …​-zsh or …​-fish) to start a container with your favorite shell.

Just look at this tiny, five-line script:

Results in this detailed and, let’s be honest, gorgeous ASCII output:

Tell me you are not at all excited to start writing complex installation flows in BASH right away?

Not only you get pretty output, but you can each executed command, it’s exit status, whether it’s been successful (green/red), as well each command’s bloody duration in milliseconds. What’s not to like?!?

Still not convinced?

Take a look at a more comprehensive example next.

In this example, we’ll download and install binaries kubectl and minikube binaries into /usr/local/bin

We provided an example script in examples/k8s-installer.sh. Please click and take a look at the source.

Here is the output of running this script:

Why do we think this type of installer is pretty awesome, compared to a silent but deadly shell script that "Jim-in-the-corner" wrote and now nobody understands?

Because:

1. The script goes out of its way to over-communicate what it does to the user.

2. It allows and reminds about a clean getaway (Ctrl-C)

3. It shares the exact command it runs and its timings so that you can eyeball issues like network congestions or network addresses, etc.

4. It shows in green exit code '0' of each command. Should any of the commands fail, you’ll see it in red.

5. It’s source code is terse, explicit, and easy to read. There is no magic. Just BASH functions.

Let’s get back to the Earth, and talk about how to install Bashmatic, and how to use it in more detail right after.

This final and most feature-rich example is not just an example – it’s a working functioning tool that can be used to install a bunch of developer dependencies on your Apple Laptop.

It’s located in bin/dev-setup and has many CLI flags:

In the example below we’ll use dev-setup script to install the following:

• Dev Tools

• PostgreSQL

• Redis

• Memcached

• Ruby 2.7.1

• NodeJS/NPM/Yarn

Despite that this is a long list, we can install it all in one command.

We’ll run this from a folder where our application is installed, because then the Ruby Version will be auto-detected from our .ruby-version file, and in addition to installing all the dependencies the script will also run bundle install and npm install (or yarn install). Not bad, huh?

This compact command line installs a ton of things, but don’t take our word for it - run it yourself. Or, at the very least enjoy this one extremely long screenshot :)

This is a great tool that colorizes nearly any other tool’s output.

Run it like so:

You might need to enter your password for SUDO.

Once it completes, run source ~/.bashrc (or whatever shell you use), and type something like ls -al or netstat -rn or ping 1.1.1.1 and notice how all of the above is nicely colored.

If you are using PostgreSQL, you are in luck! Bashmatic includes numerous helpers for PostreSQL’s CLI utility psql.

Before you begin, we recommend that you install file .psqlrc from Bashmatic’s conf directory into your home folder. While not required, this file sets up your prompt and various macros for PostgreSQL that will come very handy if you use psql with any regularity.

What is dbtop anyway?

Just like with the regular top you can see the "top" resource-consuming processes running on your local system, with dbtop you can observe a self-refreshing report of the actively running queries on up to three database servers at the same time.

Here is the pixelated screenshot of dbtop running against two live databases:

In order for this to work, you must first define database connection parameters in a YAML file located at the following PATH: ~/.db/database.yml.

Here is how the file should be organized (if you ever used Ruby on Rails, the standard config/database.yml file should be fully compatible):

Given the above file, you should be able to run:

And see the newline separated list:

Once that’s working, you should be able run dbtop:

DB Top Configuration:

You can configure the following settings for db top:

1. You can change the location of the database.yml file with db.config.set-file <filepath>

2. You can change the refresh rate of the dbtop with eg. db.top.set-refresh 0.5 (in seconds, fractional values allowed). This sets the sleep time between the screen is fully refreshed.

Bashmatic® provides a large number of functions, which are all loaded in your current shell. The functions are split into two fundamental groups:

• Functions with names beginning with a . are considered "private" functions, for example .run.env and .run.initializer

• All other functions are considered public.

The following conventions apply to all functions:

• We use the "dot" for separating namespaces, hence git.sync and gem.install.

• Function names should be self-explanatory and easy to read.

• DO NOT abbreviate words.

• All public functions must be written defensively: i.e. if the function is called from the Terminal without any arguments, and it requires arguments, the function must print its usage info and a meaningful error message.

For instance:

Now let’s run it properly:

The naming convention we use is a derivative of Google’s Bash StyleGuide, using . to separate BASH function namespaces instead of much more verbose ::.

After running the above, run bashmatic.functions function to see all available functions. You can also open the FUNCTIONS.adoc file to see the alphabetized list of all 422 functions.

To get a list of module or pattern-specific functions installed by the framework, run the following:

For instance:

You can list various modules by listing the lib sub-directory of the ${BASHMATIC_HOME} folder.

Note how we use Bashmatic® helper columnize [ columns ] to display a long list in five columns.

At a high level, the following modules are provided, in order of importance:

The following example is the actual code from a soon to be integrated AWS credentials install script. This code below checks that a user has a local ~/.aws/credentials file needed by the awscli, and in the right INI format. If it doesn’t find it, it checks for the access key CSV file in the ~/Downloads folder, and converts that if found. Now, if even that is not found, it prompts the user with instructions on how to generate a new key pair on AWS IAM website, and download it locally, thereby quickly converting and installing it as a proper credentials file. Not bad, for a compact BASH script, right? (of course, you are not seeing all of the involved functions, only the public ones).

Now, how would you use it in a script? Let’s say you need a script to upload something to AWS S3. But before you begin, wouldn’t it be nice to verify that the credentials exist, and if not – help the user install it? Yes it would.

And that is exactly what the code above does, but it looks like a DSL. because it is a DSL.

This script could be your bin/s3-uploader

Some bash files exists as libraries to be "sourced in", and others exist as scripts to be run. But users won’t always know what is what, and may try to source in a script that should be run, or vice versa - run a script that should be sourced in.

What do you, programmer, do to educate the user about correct usage of your script/library?

Bashmatic® offers a reliable way to test this:

If you’rather require a library to be sourced in, but not run, use the code as follows:

The framework comes with a bunch of automated unit tests based on the fantastic framework bats.

To run all tests:

While not every single function is tested (far from it), we do try to add tests to the critical ones.

Please see existing tests for the examples.

If you are stuck working on a monitor that does not support switching digit input from TV to PC, NOR does OS-X show the "underscan" slider in the Display Preferences, you may be forced to change the underscan manually. The process is a bit tricky, but we have a helpful script to do that:

This will reduce underscan by 5% compared to the current value. The total value is 10000, and is stored in the file /var/db/.com.apple.iokit.graphics. The tricky part is determining which of the display entries map to your problem monitor. This is what the script helps with.

Do not forget to restart after the change.

Acknowledgements: the script is an automation of the method offered on this blog post.

Submit a pull request!