Skip to main content

Getting started

So, you want to use bashutils inside your project! That's nice.

Warning​

Please, UNDER NO CIRCUMSTANCES, include the source code of bashutils in your scripts directly. Instead follow one of the methods provided below. This prevents you from doing stupid things and allows you to update bashutils easier.

Method 1 – source-ing​

For this method, simply get the bashutils.sh from somewhere and then invoke source bashutils.sh in your start script as soon as possible.

The best way to get the bashutils.sh file is to git clone https://git.staropensource.de/StarOpenSource/bashutils or git submodule add https://git.staropensource.de/StarOpenSource/bashutils bashutils in your repository, working or some temporary directory. If that's not an option, try downloading the script using curl, wget or some other download tool. If that's not an option too, simply bundle the script. That should suffice.

This method is great for collections of scripts and is generally the recommended approach.

Method 2 - Embedding into a script​

For this method you have to either split your scripts apart, so they can be concatenated into one big script with bashutils sandwhiched inbetween, or replace some comment with the contents of the bashutils.sh file.

Splitting a script​

Let's say that you have a src directory with all of your script files and a build.sh script in the repository root. For our example, let's say that the contents of the build.sh file is the following:

#!/usr/bin/env bash
echo ":: Compiling"
rm -rf output.sh

# This comment is referenced later
echo "#!/usr/bin/env bash" > example.sh
cat src/init.sh >> example.sh
cat src/checks.sh >> example.sh
cat src/run.sh >> example.sh

chmod +x output.sh

To use bashutils in this project setup, simply git submodule add https://git.staropensource.de/StarOpenSource/bashutils bashutils in your repository and then add (or for this example replace the reference comment with) this line:

cat bashutils/bashutils.sh >> example.sh

Though you may need to modify this line to match your build script's code..

Replacing a comment​

Let's say that you have one big script file, like this (for this example, this will suffice):

#!/usr/bin/env bash

echo "Hello World!"
echo "I'd like to exit now."
exit 1

To embed bashutils in this project setup, invoke git submodule add https://git.staropensource.de/StarOpenSource/bashutils bashutils, create a build script looking like this (you may need to make some modifications to the variables):

#!/usr/bin/bash
SCRIPT="example.sh"
OUTFILE="output.sh"
BASHUTILS="bashutils/bashutils.sh"

# Exit on failure
set -euo pipefail

echo ":: Copying build file"
rm -rf "${OUTFILE}"
cp "${SCRIPT}" "${OUTFILE}"

echo ":: Adding bashutils"
sed -i \
    -e "/\# bashutils init/r ${BASHUTILS}" \
    -e "/\# bashutils init/d" \
    ${OUTFILE}

... and then modify your script to include a line containing # bashutils init, like this:

#!/usr/bin/env bash

# bashutils init
info "Hello World!"
diag "I'd like to exit now."
exit 1

To make your script useable, simply invoke the build.sh script and you should your script fully working, with bashutils bundled inside.