bash3boilerplate/README.md

• Overview
• Goals
• Features
• Installation
• Changelog
• Best Practices
• Frequently Asked Questions
• Authors
• License

Overview

When hacking up Bash scripts, there are often higher level things like logging, configuration, command-line argument parsing that:

• You need every time
• Come with a number of pitfalls to get right
• Keep you from your actual work

Here's an attempt to bundle those things in a generalized way so that they are reusable as-is in most scripts.

Goals

Delete-key-friendly. I propose using main.sh as a base and removing the parts you don't need, rather than introducing a ton of packages, includes, compilers, etc.

Aiming for portability, I'm targeting Bash 3 (OSX still ships with 3 for instance). If you're going to ask people to install Bash 4 first, you might as well pick a more advanced language as a dependency.

We're automatically testing BASH3 Boilerplate and it's proven to work on:

• Linux GNU bash, version 4.2.25(1)-release (x86_64-pc-linux-gnu)
• OSX GNU bash, version 3.2.51(1)-release (x86_64-apple-darwin13)

Features

• Structure
• Safe defaults (break on error, pipefail, etc)
• Configuration by environment variables
• Configuration by command-line arguments (definitions parsed from help info, so no duplication needed)
• Magic variables like __file, __dir, and __os
• Logging that supports colors and is compatible with Syslog Severity levels as well as the The twelve-factor app

Installation

There are 3 ways you can install (parts of) b3bp:

1. Just get the main template: wget https://raw.githubusercontent.com/kvz/bash3boilerplate/master/main.sh
2. Clone the entire project: git clone git@github.com:kvz/bash3boilerplate.git
3. As of v1.0.3, b3bp can be installed as a package.json dependency via: npm install --save bash3boilerplate

Although 3 introduces a node.js dependency, this does allow for easy version pinning and distribution in environments that already have this prerequisite. But nothing prevents you from just using curl and keep your project or build system low on external dependencies.

Changelog

Please see the CHANGELOG.md file.

Best practices

As of v1.0.3, b3bp adds some nice re-usable libraries in ./src. Later on we'll be using snippets inside this directory to build custom packages. In order to make the snippets in ./src more useful, we recommend these guidelines.

Library exports

It's nice to have a bash package that can be used in the terminal and also be invoked as a command line function. To achieve this the exporting of your functionality should follow this pattern:

if [ "${BASH_SOURCE[0]}" != ${0} ]; then
  export -f my_script
else
  my_script "${@}"
  exit $?
fi

This allows a user to source your script or invoke as a script.

# Running as a script
$ ./my_script.sh some args --blah
# Sourcing the script
$ source my_script.sh
$ my_script some more args --blah

(taken from the bpkg project)

Miscellaneous

• In functions, use local before every variable declaration
• This project settles on two spaces for tabs

Frequently Asked Questions

Please see the FAQ.md file.

Authors

• Kevin van Zonneveld
• Izaak Beekman
• Alexander Rathai
• Dr. Damian Rouson (documentation, feedback)
• @jokajak (documentation)
• Gabriel A. Devenyi (feedback)
• @bravo-kernel (feedback)

License

Copyright (c) 2013 Kevin van Zonneveld and contributors. Licensed under MIT. You are not obligated to bundle the LICENSE file with your b3bp projects as long as you leave these references intact.