This is a small bash library called command_runner. It can run a list of commands in a script and report the results. In comparison to using a plain bash script you have a better control over execution and printing. Per default only the outputs of the failed commands will be printed, the rest will only be summarized. You can decide if you want to run all commands even if some failed or if you want to stop after first failure. The report will in any case contain all configured commands with their respective execution status. The overall status code will be propagated consistently which enables the usage of the command_runner in the scope of a larger tooling setup.

Next steps:

• Have a look at the Example use case.
• If you want to try it out on your machine, you will find executable examples here: examples.
• If you want to contribute or change anything for your local needs, please have a look at the tests here: test.
• Check out the API Reference for detailed information.

The main motivation of developing this library was the usage as a simple CI. In most projects you will want to run some commands repeatedly. Like run linters, build, deploy, test your software, etc. The command_runner provides you with a simple API to collect these commands in a single script and have a nice report after execution.

An example could look like:

# my_project_ci.sh

# Import command runner script.
SCRIPT_DIRECTORY="$(dirname "${BASH_SOURCE[0]}")"
source "$SCRIPT_DIRECTORY/../command_runner/command_runner.sh"

# Add the following line if you want to stop on first failure
# and skip all remaining commands:
# command_runner_stop_on_failure

# Add commands like you would run them in the command line.
# cra is an alias for command_runner_add.
cra "$SCRIPT_DIRECTORY/check_clang_format.sh"
cra "bazel build //..."
cra "bazel test //..."
cra "bazel test --config=sanitizer //..."

# Run commands.
# crr is an alias for command_runner_run.
# Passing "$@" is not required, but helpful to run the whole script with [-v, -s].
crr "$@"

If all commands pass, a short summary will be printed and the return value will be 0:

If any command fails, the output of this command will be printed in the Errors section and the return value will be 1:

Per default all commands are executed. If you want to stop on first failure and skip the remaining commands, please add command_runner_stop_on_failure to your script. The output will then be:

Per default only the logs of failed commands will be printed, but the verbosity can be configured. Please check the API Reference.

Use this function to add a command for later execution. Put the command in quotes, otherwise add it like you would run it from the command line. E.g.

command_runner_add "ls -l"

The command is expected to return 0 to be counted as PASSED.

Short alias for command_runner_add. Improves brevity and focus on the commands at hand.

Use this function the same way as command_runner_add but with an additional expected return value. Use it if you expect a command to fail, but want to count it as PASSED nevertheless. This is useful to temporarily accept failing commands but still run them or to explicitly test for true negatives. E.g.

command_runner_add_with_expectation "ls invalid_path -l" 2

The command is expected to return the given value to be counted as PASSED.

Use this function to run the previously added commands. Commands will be executed in the order they were added. The exact logging behavior depends on the output settings. To run the commands with the default output setting (only the output of failed commands will be printed) use:

command_runner_run

To run the commands with the verbose output setting (all outputs will be printed) use:

command_runner_run -v

To run the commands with the streamed output setting (all outputs will be printed during execution) use:

command_runner_run -s

In all cases all failed commands and a summary will be printed. The return value will be 0 if all commands passed and 1 if at least one command failed.

Short alias for command_runner_run. Improves brevity and focus on the commands at hand.

Use this function to skip remaining commands after first failure. This is useful if commands depend on each other like in installation scripts or if you want to save runtime in the failure case.

Use this function to disable colored output.

Use this function to enable verbose output. Verbose output means that the logs of all commands will be printed AFTER execution. Otherwise only the logs of failed commands will be printed. The output can either be verbose OR streamed, not both.

Use this function to enable streamed output. Streamed output means that the logs of all commands will be printed DURING execution. This is helpful if you want to observe the output of long running commands. The output can either be verbose OR streamed, not both.