How to Build a Reusable Shell Function Library

Sourcing a file executes it in the caller’s current shell. That makes shell libraries convenient, but it also means an accidental exit, option change, directory change, or variable collision can corrupt the caller.

State the supported shell

A POSIX sh library cannot use Bash arrays or [[ ... ]]. A Bash library should say so and be sourced only from Bash scripts. Do not put a shebang on a library and assume it enforces anything when sourced; the current interpreter remains in control.

Use a project prefix to reduce collisions:

dc_log_info() {
  printf '%s\n' "INFO: $*" >&2
}

dc_require_command() {
  command -v "$1" >/dev/null 2>&1 || {
    dc_log_info "missing command: $1"
    return 127
  }
}

Library functions should return; they should not exit the entire caller unless that is the explicitly documented contract. Keep variables local where the target shell supports it, or namespace global scratch variables and restore them carefully in portable code.

Make sourcing quiet and repeatable

Import-time code should define functions and constants, not print banners, start processes, run network calls, or change directories. An optional load guard can prevent duplicate initialization, but it should not hide a library-version conflict.

Pass values as arguments instead of reading ambient globals. Send functional output to standard output and diagnostics to standard error so callers can safely use command substitution. Document whether functions accept arbitrary filenames, read standard input, or mutate files.

Test the integration boundary

Launch a fresh supported shell, source the library, invoke functions with spaces, glob characters, empty values, and expected failures, then check status and output. Run ShellCheck with the source relationship visible so it can analyze referenced definitions.

Version shared libraries with the scripts that consume them. Installing one mutable library into a global path can silently change many jobs at once; for critical automation, a vendored or packaged version gives reviewable upgrades and rollback.

Sources: