The whole course has taken one thing for granted: that the interpreter is Bash 5 on Ubuntu 24.04. It is a reasonable assumption for srv-veloz-01/02/03, and that is why we have used associative arrays, mapfile, [[ ]], ${s^^} and set -o pipefail without thinking twice. But the day someone has to write the entrypoint.sh for the veloz-api Alpine container, or a boot script that runs before Bash is available, or a tool a colleague will run on their macOS, that assumption breaks and the script fails with baffling errors. This lesson explains what POSIX is, which of our constructs are bashisms, what their equivalents are, why external tools cause more trouble than the shell itself, how to check portability and — most importantly — when it is worth it and when it is a burden.

1. What POSIX is and what a bashism is
2. The real-world picture: who /bin/sh is on each system
3. Table of bashisms and their POSIX equivalent
4. Details you have to know when dropping down to POSIX
5. External tools hurt more than the shell
6. How to check portability
7. The design decision, with an explicit criterion for Veloz Envíos
8. Declaring the dependency: checking BASH_VERSINFO
9. What each Bash version brings and the macOS problem
10. Module 8 in review

POSIX is a standard (IEEE 1003.1) that defines, among many other things, the shell language: which syntax any shell claiming conformance must understand. It is the lowest common denominator, and it is deliberately austere: it has no arrays, no [[ ]], no string substitution in expansions.

A bashism is any construct Bash understands and the standard does not require. They are not errors — they are the reasons Bash is convenient — but they only work where Bash is present. The problem arises from one specific confusion: writing #!/bin/sh on the first line and using Bash syntax inside. On Ubuntu, if you also test it by running bash script.sh, it works; in the Alpine container, where /bin/sh is a different program, it fails.

The two dangerous rows are RHEL's and macOS', for opposite reasons. On RHEL your script with bashisms and #!/bin/sh works, so nobody detects the problem until it reaches Debian. On macOS the interpreter is called bash but it is version 3.2, from 2006 — Apple does not update it for licensing reasons — so a script that is perfectly correct for Bash 5 fails with cryptic messages.

The typical error looks like this:

[[: not found is the unmistakable signature of a bashism under dash: it is not a syntax error, it is that dash is looking for a command called [[.

[ ] is not [[ ]]. It is a command, not syntax, so its arguments suffer word splitting. [ $a = $b ] with an empty $a becomes [ = value ] and gives a syntax error. With quotes — [ "$a" = "$b" ] — it always works. Use =, not ==, and -a/-o are obsolete: chain with && and || between two [ ].

No pipefail. This is the most serious loss, because cmd1 | cmd2 returns cmd2's code and a failure of the first goes unnoticed (05-03). The workable way out is to break the pipeline: write the first stage to a temp file with mktemp, check its exit code and read the temp file in the second stage. In practice, a POSIX script is restructured so as not to chain commands whose failure matters.

No arrays. The substitute is the positional parameters:

It is a single set per scope, so if you need two lists at once, you either keep one inside a function or move to awk.

No local, in theory. The standard does not include it, but dash, ash, ksh and zsh implement it. The practical recommendation: use it, and document in the header that the script requires a shell with local.

This is the part almost everybody underestimates. You can write an impeccable POSIX script and have it fail on macOS because sed -i works differently. Linux uses GNU coreutils; macOS and the BSDs use the BSD tools; Alpine uses BusyBox, which is a third, reduced implementation.

Three strategies, in order of preference:

1. Stick to each tool's POSIX options. sed 's/a/b/' without -i, grep -E, find -exec. It is the most robust and almost always enough.
2. Detect the variant at startup and adapt:

3. Declare the dependency: require coreutils and check it with veloz_require (06-03). On macOS they are installed with brew install coreutils, though they end up with a g prefix (gsed, gdate).

Three complementary tools, plus a real run:

checkbashisms is the specialist and detects things ShellCheck does not flag; shellcheck -s sh integrates with the rest of the flow and explains the why; dash -n validates the syntax with the interpreter that will actually be used on Debian. But the definitive check is running it where it is going to run:

There you discover the bashisms and the BusyBox differences at the same time, and the latter are half the problem. It deserves a CI job (08-05) alongside the ShellCheck one.

Pure POSIX is not "better": it is a restriction you pay for in readability and in processes. A ${s^^} becomes a tr with its fork, and an associative array that solved an aggregation in ten lines becomes a sorted temp file. Writing in POSIX something that will always run on Ubuntu is paying a cost and buying nothing.

Criterion for the toolkit, written down and applied:

• lib/common.sh and the five scripts in bin/ remain Bash 5, with #!/usr/bin/env bash, associative arrays, [[ ]], mapfile and set -euo pipefail. They run on three identical servers we administer ourselves; giving up those tools would make the code worse for no gain at all.
• The entrypoint.sh of the veloz-api container is written in pure POSIX with #!/bin/sh. The base image is Alpine, it does not ship Bash, and adding it just for startup means growing the image and its attack surface. The script is short — it checks environment variables, waits for the database and execs the service — exactly the kind of logic POSIX covers effortlessly.

Not a single bashism: [ ] instead of [[ ]], $(( )) which is POSIX, : with ${var:=} and ${var:?}, echo with no options and a final exec so the service inherits PID 1 and receives the signals (05-02). The decision is documented in the header, which is as important as the decision itself.

If a script requires Bash 4 or higher, say so and fail early with a clear message, instead of blowing up fifty lines later with "syntax error near unexpected token". The check goes at the top of lib/common.sh, right after the shebang, and uses BASH_VERSINFO (01-02):

Two details about the code. The first check is written with [ ] and echo on purpose: if the interpreter turns out to be dash, those two lines have to work in order to deliver the message; a [[ ]] here would produce exactly the cryptic error we are trying to avoid. And the message says what to do, not just what is missing: an error that points to the solution saves half an hour for whoever hits it.

The practical boundary is Bash 4.0: almost everything that makes modern Bash comfortable arrived there. Ubuntu 24.04 ships 5.2, so there is no problem across the fleet.

The problem is macOS, which is still on 3.2 from 2006 because of the GPLv3 license of the later versions. If a colleague develops on a Mac, their scripts will fail when using declare -A or mapfile even though they work on the servers. Three possible answers: install a modern Bash with Homebrew and use #!/usr/bin/env bash with the new one first in the PATH — the normal option; stick to Bash 3.2, which is giving up too much; or develop inside a container with the same image as production, which additionally eliminates the rest of the tool differences from section 5.

The module started with three questions about the toolkit: is it understandable? is it fast? is it secure? Seven lessons later, ~/veloz-ops/ is a different thing:

And all of it without adding a single new feature. That is the module's idea: the difference between a script that works and software you can rely on is not in what it does, but in how it is made.

• Putting #!/bin/sh and writing Bash. The central mistake. If you use bashisms, the shebang is #!/usr/bin/env bash.
• Testing with bash script.sh a script that declares sh. The shebang is ignored when you invoke it that way, and the problem stays hidden. Test with dash script.sh.
• Believing POSIX is "safer" or "better". It is more restrictive: choosing it without need produces longer, slower and harder-to-read code.
• Forgetting the quotes in [ ]. [[ ]] forgave you; here an empty variable produces a syntax error.
• Assuming the tools are GNU. sed -i, date -d and readlink -f do not exist in the same form on macOS or BusyBox, and no shell helps you there.
• Tip: an Alpine container in CI costs seconds and detects the bashisms and the BusyBox differences at the same time.
• Tip: write the decision in the file header. "Requires Bash 4.3+" or "Pure POSIX: the image has no bash" stops the next person from undoing it by accident.

Exercise 1. Convert this fragment to pure POSIX keeping the behavior.

Exercise 2. Write a veloz_days_ago function that returns the date N days ago in YYYY-MM-DD format and works with both GNU and BSD date.

Exercise 3. A colleague reports that daily-report.sh fails on their macOS with declare: -A: invalid option. Explain the cause and propose two solutions with their trade-offs.

Solution 1.

Four substitutions: the array becomes set -- and "$@"; the pattern comparison [[ $c == V* ]] becomes case, which is the POSIX way of comparing against patterns; ${c^^} becomes tr; and echo -e becomes printf, which interprets \t portably and also avoids the problem of echo -e printing a literal -e in some shells.

Solution 2.

The detection is done by trying a GNU-only option and discarding its output and its error. The truly universal alternative is epoch arithmetic — date -d "@$(( $(date +%s) - 86400 * $1 ))" — but it has the same problem converting back, and it also ignores daylight-saving changes, so variant detection is preferable.

Solution 3. The cause is that macOS ships Bash 3.2, older than the associative arrays that arrived in 4.0, and #!/usr/bin/env bash resolves to the system's /bin/bash. Two solutions:

• Install a modern Bash with brew install bash and put its directory ahead in the PATH, so that env bash finds the 5.x one. Trade-off: each person has to configure their machine, and a badly ordered PATH silently reproduces the failure.
• Develop in a container with the same image as production. Trade-off: a slightly heavier workflow; advantage: it also eliminates the sed, date and stat differences from section 5, which would show up anyway.

Rewriting the toolkit for Bash 3.2 would be a third option, and it is the worst: it penalizes three servers to accommodate one laptop. In any case, the BASH_VERSINFO check from section 8 would have turned that cryptic error into a message explaining what to do.

Portability is a decision, not an automatic virtue. POSIX defines the shell's lowest common denominator, and everything Bash adds on top — [[ ]], arrays, ${s//a/b}, ${s^^}, mapfile, <<<, <( ), +=, set -o pipefail, trap ERR — is a bashism that disappears the moment /bin/sh is dash on Debian, ash on Alpine or ksh on another Unix; the error [[: not found is its signature. The equivalence table covers the essentials: [ "$a" = "$b" ] with mandatory quotes, case for comparing against patterns, set -- and "$@" as a substitute for arrays, tr and sed instead of the string expansions, . instead of source, printf instead of echo -e and restructuring the code wherever pipefail is missing. But the bigger problem is not in the shell but in the external tools: sed -i, date -d, readlink -f, grep -P and stat behave differently on GNU, BSD and BusyBox, and against that there are only three strategies — stick to the POSIX options, detect the variant at startup or declare the dependency on coreutils. Portability is checked, not assumed: checkbashisms, shellcheck -s sh, dash -n and, above all, a real run in an Alpine container inside CI. Veloz Envíos' criterion is written down: lib/common.sh and the five scripts in bin/ remain Bash 5 because they run on three identical servers and giving up their tools would buy nothing, whereas the entrypoint.sh of the veloz-api container is written in pure POSIX because the Alpine image has no Bash and its logic is short. That dependency is declared and checked with BASH_VERSINFO at startup, in [ ] and echo so the message gets through even if the interpreter is dash, and saying what to do and not just what is missing. The practical boundary is Bash 4.0 — associative arrays, mapfile, ${s^^} — with declare -n in 4.3, and the recurring obstacle is macOS' Bash 3.2, which is solved with Homebrew or by developing in a container.

With this Module 8 closes, and with it the toolkit's transformation: the same five scripts and the same library that started the module are now readable, fast, audited, versioned, analyzed, tested and with their portability decided, without having added a single new feature. You already know how to write Bash and you already know how to write it well. What is left is putting it all together. Module 9 is five complete projects built step by step, applying everything learned at once: a system information collector (09-01), a log analyzer that aggregates, detects patterns and generates reports (09-02), an automated backup system with retention, verification and a tested restore (09-03), a network monitor with thresholds and alerts (09-04) and, as the course's closing piece, the final integration of the toolkit (09-05), where the pieces of the four previous projects are unified into a single tool, installable, versioned, tested and deployed across the Veloz Envíos fleet.