Bash Boilerplate

A collection of Bash starter scripts for easily creating safe and usefulcommand line programs.

Bash Boilerplate is great for making standalone, portable, single-file command lineprograms as well as shell initialization functions. For a frameworkapproach that's useful for task and build files, try Bask,a pure Bash mini-framework for command-centric Bash scripts.

Scripts

bash-simple

A simple bash script with some basic strictness checks and help features.Useful for simple programs that don't have many features and don't takeoptions other than help.

Notable Features

• Strict Mode,
• Help template, printable with -h or --help.

bash-simple-plus

A simple bash script with some basic strictness checks, option parsing,help features, easy debug printing. Useful for regular scripts.

Notable Features

• Strict Mode,
• Help template, printable with -h or --help,
• debug printing with --debug flag,
• _exit_1 and _warn functions for error messages,
• Option parsing.

bash-subcommands

An example of a bash program with subcommands. This contains lots of featuresand should be usable for creating bash programs that do multiple relatedtasks.

Notable Features

• Strict Mode,
• Help template, printable with -h or --help,
• debug printing with --debug flag,
• _exit_1 and _warn functions for error messages,
• Option normalization and parsing,
• Automatic arbitrary subcommand loading,
• An nice, clean pattern for specifying per-subcommand help,
• Built-in subcommands for help, version, and subcommand listing,
• Conventions for distinguishing between functions and program subcommands,
• Useful utility functions.

functions.bash

Shell function examples and boilerplate. The functions in this file areintended to be included in the interactive shell, which can be done bydefining them in a shell init file like ~/.bashrc.

helpers.bash

Helper functions. These functions are primarily intended to be used withinscripts, but can be adapted for use as shell functions.

Notes

ShellCheck

Use it. It's super useful.

ShellCheck is a static analysis and linting tool for sh/bash scripts.It's mainly focused on handling typical beginner and intermediate levelsyntax errors and pitfalls where the shell just gives a cryptic errormessage or strange behavior, but it also reports on a few more advancedissues where corner cases can cause delayed failures.

Links

• http://www.shellcheck.net/
• http://www.shellcheck.net/about.html
• https://github.com/koalaman/shellcheck

It can be used with Vim viaSyntastic, Emacs viaFlycheck, Sublime Text 3 viaSublimeLinter, VS Code via vscode-shellcheck, and Atom vialinter,atom-lint,or linter-shellcheck.

Bash "Strict Mode"

These boilerplate scripts use some common settings for enforcing strictnessin Bash scripts, thereby preventing some errors.

For some additional background, see Aaron Maxwell's"Unofficial Bash Strict Mode" (redsymbol.net)post.

Simple 'Strict Mode' TL;DR

Add this to the top of every script (note: an extended version of this isalready included in the boilerplate scripts):

# Bash 'Strict Mode'
# http://redsymbol.net/articles/unofficial-bash-strict-mode
# https://github.com/xwmx/bash-boilerplate#bash-strict-mode
set -o nounset
set -o errexit
set -o pipefail
IFS=$'\n\t'

set -o nounset / set -u

Treat unset variables and parameters other than the special parameters @ or* as an error when performing parameter expansion. An 'unbound variable'error message will be written to the standard error, and a non-interactiveshell will exit.

Usage

Short form:

set -u

Long form:

set -o nounset

Parameter Expansion

Parameter expansion can be used to test for unset variables when using set -o nounset.

http://www.gnu.org/software/bash/manual/bashref.html#Shell-Parameter-Expansion

The two approaches that are probably the most appropriate are:

${parameter:-word}
  If parameter is unset or null, the expansion of word is substituted.
  Otherwise, the value of parameter is substituted. In other words, "word"
  acts as a default value when the value of "$parameter" is blank. If "word"
  is not present, then the default is blank (essentially an empty string).

${parameter:?word}
  If parameter is null or unset, the expansion of word (or a message to that
  effect if word is not present) is written to the standard error and the
  shell, if it is not interactive, exits. Otherwise, the value of parameter
  is substituted.

Parameter Expansion Examples

Arrays:

${some_array[@]:-}              # blank default value
${some_array[*]:-}              # blank default value
${some_array[0]:-}              # blank default value
${some_array[0]:-default_value} # default value: the string 'default_value'

Positional variables:

${1:-alternative} # default value: the string 'alternative'
${2:-}            # blank default value

With an error message:

${1:?'error message'}  # exit with 'error message' if variable is unbound

set -o errexit / set -e

Exit immediately if a pipeline returns non-zero.

Usage

Short form:

set -e

Long form:

set -o errexit

Using set -o errexit with read -rd ''

set -o errexit is super useful for avoiding scary errors, but there are somethings to watch out for. When using read -rd '' with a heredoc, theexit status is non-zero, even though there isn't an error, and thissetting then causes the script to exit. read -rd '' is equivalentto read -d $'\0', which means read until it finds a NUL byte, butit reaches the end of the heredoc without finding one and exits witha 1 status. Therefore, when reading from heredocs with set -e,there are three potential solutions:

Solution 1. set +e / set -e again:

set +e
read -rd '' variable <<HEREDOC
Example text.
HEREDOC
set -e

Solution 2. <<HEREDOC || true:

read -rd '' variable <<HEREDOC || true
Example text.
HEREDOC

Solution 3. Don't use set -e or set -o errexit at all.

More information:

'builtin "read -d" behaves differently after "set -e"' (lists.gnu.org)

set -o pipefail

Return value of a pipeline is the value of the last (rightmost) command toexit with a non-zero status, or zero if all commands in the pipeline exitsuccessfully.

Usage

Long form (no short form available):

set -o pipefail

$IFS

Set IFS to just newline and tab.

IFS=$'\n\t'

For some background, seeFilenames and Pathnames in Shell: How to do it Correctly (dwheeler.com)

Misc Notes

Explicitness and clarity are generally preferable, especially since bash canbe difficult to read. This leads to noisier, longer code, but should beeasier to maintain. As a result, some general design preferences:

• Use leading underscores on internal variable and function names in orderto avoid name collisions. For unintentionally global variables definedwithout local, such as those defined outside of a function orautomatically through a for loop, prefix with double underscores.
• Always use braces when referencing variables, preferring ${NAME} insteadof $NAME. Braces are only required for variable references in some cases,but the cognitive overhead involved in keeping track of which cases requirebraces can be reduced by simply always using them.
• Prefer printf over echo. For more information, see:http://unix.stackexchange.com/a/65819
• Prefer $_explicit_variable_name over names like $var.
• Use the #!/usr/bin/env bash shebang in order to run the preferredBash version rather than hard-coding a bash executable path.
• Prefer splitting statements across multiple lines rather than writingone-liners.
• Group related code into sections with large, easily scannable headers.
• Describe behavior in comments as much as possible, assuming the reader isa programmer familiar with the shell, but not necessarily experienced writingshell scripts.

Resources

• About ShellCheck (shellcheck.net)
• Bash Reference Manual (gnu.org)
• POSIX: Shell Command Language (pubs.opengroup.org)
• The Art of Command Line (github.com)
• "Unofficial Bash Strict Mode" (redsymbol.net)
• Filenames and Pathnames in Shell: How to do it Correctly (dwheeler.com)
• Understanding Exit Codes and how to use them in bash scripts (bencane.com)
• 'builtin "read -d" behaves differently after "set -e"' (lists.gnu.org)
• Bash Pitfalls (mywiki.wooledge.org)
• Rich’s sh (POSIX shell) tricks (etalabs.net)
• Writing Robust Bash Shell Scripts (davidpashley.com)
• Bash Strict Mode (github.com)
• pure bash bible - A collection of pure bash alternatives to external processes (github.com)

Related Projects

• oxyc/bash-boilerplate
• e36freak/templates
• connermcd/bash-boilerplate
• chrisopedia/bash-boilerplate
• ShaneKilkelly/manuel
• kvz/bash3boilerplate
• ralish/bash-script-template

Examples

Scripts based on this project.

• airport - A command line tool for Wi-Fi on macOS.
• bask - A pure Bash mini-framework for command-centric Bash scripts.
• bindle - A configuration and dotfile management tool for your personal unix-like computer.
• hosts - Command line hosts file editor in a single portable script.
• ❯ nb - CLI note-taking, bookmarking, and archiving with encryption, advanced search, Git-backed versioning and syncing, Pandoc-backed conversion, and more in a single portable script.
• notes-app-cli - A command line interface for Notes.app on macOS.
• pb - A tiny wrapper combining pbcopy & pbpaste in a single command.
• search.sh - A command line search multi-tool.
• user - Command line interface for common macOS user account operations.
• vbox - A streamlined interface for VBoxManage, the VirtualBox command line tool.

Copyright (c) 2015 William Melody • hi@williammelody.com