Home

Awesome

Shell Scripting Templates and Utilities

A collection of BASH utility functions and script templates used to ease the creation of portable and hardened BASH scripts with sane defaults.

Usage

There are two Script Templates located in the root level of this repository. The usage of these templates is described in detail below.

BASH Utility functions are located within the utilities/ folder.

Complex sed find/replace operations are supported with the files located in sedfiles/. Read the usage instructions.

Automated testing is provided using BATS. All tests are in the tests/ repo. A git pre-commit hook provides automated testing is located in the .hooks/ directory. Read about how to install the hook.

Bash Script Templates Usage

To create a new script, copy one of the script templates to a new file and make it executable chmod 755 [newscript].sh. Place your custom script logic within the _mainScript_ function at the top of the script.

Script Templates

There are two templates located at the root level of this repository.

Code Organization

The script templates are roughly split into three sections:

Default Options

These default options and global variables are included in the templates and used throughout the utility functions. CLI flags to set/unset them are:

You can add custom script options and flags to the _parseOptions_ function.

Script Initialization

The bottom of the script template file contains a block which initializes the script. Comment, uncomment, or change the settings here for your needs

trap '_trapCleanup_ ${LINENO} ${BASH_LINENO} "${BASH_COMMAND}" "${FUNCNAME[*]}" "${0}" "${BASH_SOURCE[0]}"' EXIT INT TERM SIGINT SIGQUIT SIGTERM ERR

# Trap errors in subshells and functions
set -o errtrace

# Exit on error. Append '||true' if you expect an error
set -o errexit

# Use last non-zero exit code in a pipeline
set -o pipefail

# Confirm we have BASH greater than v4
[ "${BASH_VERSINFO:-0}" -ge 4 ] || {
    printf "%s\n" "ERROR: BASH_VERSINFO is '${BASH_VERSINFO:-0}'.  This script requires BASH v4 or greater."
    exit 1
}

# Make `for f in *.txt` work when `*.txt` matches zero files
shopt -s nullglob globstar

# Set IFS to preferred implementation
IFS=$' \n\t'

# Run in debug mode
# set -o xtrace

# Source utility functions
_sourceUtilities_

# Initialize color constants
_setColors_

# Disallow expansion of unset variables
set -o nounset

# Force arguments when invoking the script
# [[ $# -eq 0 ]] && _parseOptions_ "-h"

# Parse arguments passed to script
_parseOptions_ "$@"

# Create a temp directory '$TMP_DIR'
# _makeTempDir_ "$(basename "$0")"

# Acquire script lock
# _acquireScriptLock_

# Source GNU utilities for use on MacOS
# _useGNUUtils_

# Run the main logic script
_mainScript_

# Exit cleanly
_safeExit_

Utility Functions

The files within utilities/ contain BASH functions which can be used in your scripts. Each included function includes detailed usage information. Read the inline comments within the code for detailed usage instructions.

Including Utility Functions

Within the utilities folder are many BASH functions meant to ease development of more complicated scripts. These can be included in the template in two ways.

1. Copy and paste into template_standalone.sh

You can copy any complete function from the Utilities and place it into your script. Copy it beneath the ### Custom utility functions line. Scripts created this way are fully portable among systems

2. Source all the utility files by using template.sh

template.sh contains a function to source all the utility files into the script. IMPORTANT: You will need to update the paths within the _sourceUtilities_ function to ensure your script can find this repository.

alerts.bash

Basic alerting, logging, and setting color functions (included in scriptTemplate.sh by default). Print messages to stdout and to a user specified logfile using the following functions.

debug "some text"     # Printed only when in verbose (-v) mode
info "some text"      # Basic informational messages
notice "some text"    # Messages which should be read. Brighter than 'info'
warning "some text"   # Non-critical warnings
error "some text"     # Prints errors and the function stack but does not stop the script.
fatal "some text"     # Fatal errors. Exits the script
success "some text"   # Prints a success message
header "some text"    # Prints a header element
dryrun "some text"    # Prints commands that would be run if not in dry run (-n) mode

The following global variables must be set for the alert functions to work

arrays.bash

Utility functions for working with arrays.

checks.bash

Functions for validating common use-cases

dates.bash

Functions for working with dates and time.

debug.bash

Functions to aid in debugging BASH scripts

files.bash

Functions for working with files.

macOS.bash

Functions useful when writing scripts to be run on macOS

misc.bash

Miscellaneous functions

services.bash

Functions to work with external services

strings.bash

Functions for string manipulation

template_utils.bash

Functions required to allow the script template and alert functions to be used

Coding conventions

A Note on Code Reuse and Prior Art

I compiled these scripting utilities over many years without having an intention to make them public. As a novice programmer, I have Googled, GitHubbed, and StackExchanged a path to solve my own scripting needs. I often lift a function whole-cloth from a GitHub repo don't keep track of its original location. I have done my best within these files to recreate my footsteps and give credit to the original creators of the code when possible. Unfortunately, I fear that I missed as many as I found. My goal in making this repository public is not to take credit for the code written by others. If you recognize something that I didn't credit, please let me know.

Contributing

Setup

  1. Install Python 3.11 and Poetry
  2. Clone this repository. git clone https://github.com/natelandau/shell-scripting-templates.git
  3. Install the Poetry environment with poetry install.
  4. Activate your Poetry environment with poetry shell.
  5. Install the pre-commit hooks with pre-commit install --install-hooks.

Developing

License

MIT