You have four scripts in ~/scripts and log() is written four times. error() too. run() is on its third copy. The day you decide the log should carry the level as well as the date you will have to edit four files and remember all four; and the day you forget one, you will have a script that logs differently without anybody finding out until it matters. Functions solve that, but not only that: a well-named function turns ten cryptic lines into one line that reads like a sentence. This lesson is about when to extract them, about the two traps Bash reserves for people coming from other languages — dynamic scope and a return that only returns numbers — and about how to build a real library, with robust loading, guards and tests. By the end, lib/common.sh will exist and the earlier scripts will use it.

1. When to extract a function
2. Syntax, and why we do not use function
3. A function's arguments are its own
4. Scope: local and Bash's dynamic scope
5. Returning values: return only returns a number
6. Predicate functions
7. Recursion, and overriding commands
8. Libraries: lib/common.sh
9. What a library should and should not do
10. Minimal tests without frameworks
11. Application: refactoring the scripts

Three criteria, and it is enough for one of them to hold:

• The rule of three. You have written the same thing for the third time: the first may be coincidence, the second impatience; the third is a function.
• The block needs a comment to be understood. If you were about to write # checks whether the release exists and is not empty, that comment is in fact the name: release_exists(). And if there are more than two levels of nesting, as we warned in 04-04, a third level is nearly always a missing function.

The name matters as much as the code: a good name is a verb or a predicate, it describes what it does and not how, and it makes the call read without comments. Compare if [[ -d /opt/tramontana/releases/$v && -f /opt/tramontana/releases/$v/app.jar ]] with if release_exists "$v". And a note on balance: a one-line function used exactly once is usually noise. The measure is not "the more the better", but "let each name save an explanation".

Bash accepts name() { body; } (POSIX), function name { body; } (a Bash/ksh extension) and the mixture function name() { ... }. We always use the first: it is the only one that works in any POSIX shell, it is the one shellcheck expects by default, and saving the parentheses gains you nothing. Syntax details that cause mysterious errors:

• The body between { } needs spaces after { and before }, because { is a reserved word, not a symbol, and the last statement before } needs a ; or a newline.
• Functions must be defined before they are used: Bash reads the file from top to bottom. Hence why in 04-07 we put main "$@" as the script's last line.
• A function and an alias with the same name clash, and the alias wins: another reason not to overuse them.

declare -f name shows the code of an already-defined function and declare -F lists the names: they are the equivalent of declare -p for variables, very useful when you are unsure which version has been loaded.

Inside a function, $1, $@ and $# are not the script's: they are the call's. $0, by contrast, is still the script's name.

It is the number one confusion for beginners: calling the function expecting it to "see" the script's arguments. If you want to pass them, do it explicitly with show "$@", which you know from 04-03 is the only form that respects spaces. And notice ${1:-empty}: with set -u active, reading $1 in a function with no arguments aborts the script, so a default value is mandatory if the argument can be missing.

Every variable created inside a function must be declared local. Without local, the variable is global and outlives the function, with entertaining consequences:

In the first case count trampled the caller's i and the outer loop printed 3 three times instead of a b c. A local i fixes it. With generic names such as i, n, tmp or line this happens constantly.

Now the part that surprises people coming from other languages. Bash has dynamic scope, not lexical: a local variable is visible inside the functions that function calls too, even if they are defined in another file.

In a lexically scoped language — Python, Java, C — inner would never see that variable, because it only sees what is in the text surrounding it; in Bash it sees whatever is in the call stack. It has a legitimate use — passing context without arguments — but it is above all invisible coupling: do not rely on it, declare local everywhere and pass the data as arguments.

300 turned into 44, because return accepts only an integer from 0 to 255 and the value is truncated modulo 256. return is not "return a result": it is "return an exit code", exactly the same concept as in 04-01 and 04-04. To return data there are three routes:

The underscore in _major is not a whim: if the caller had a variable named exactly the same as the nameref, Bash would give a circular name reference error. Prefixing namerefs with _ reduces that collision to a practical impossibility.

The course's rule: stdout by default, and a nameref only when you return several values or the subshell is a measured problem, not an imagined one.

A function that only answers yes or no must return 0 for "yes" and be used directly in an if, with no == true and no intermediate variables.

Neither of them has a return: a function returns the code of its last statement, and the last statement is precisely the test. Writing if ...; then return 0; else return 1; fi is four times longer and does the same thing.

A warning that links to 04-06: if the last statement can legitimately fail — a (( counter )) that is 0, a grep with no matches — the function will return 1 and, with set -e, will bring the script down. That is why log() ends with an explicit return 0.

Bash supports recursion, but it is rarely the answer: there is no tail-call optimisation, FUNCNEST limits the depth, and almost everything recursive an administrator does — walking a directory tree — is solved better and faster by find. What is useful is overriding a command with a function, typically to add safety or logging; the key is being able to call the original:

command ignores functions and aliases and runs the binary or builtin; builtin forces the shell's builtin (useful if you wrap cd or echo). Without one of the two, the function would call itself for ever. And a warning: do not override commands in a shared library; having rm do odd things ten metres away from where it is written is an excellent way of ruining somebody's afternoon.

We create ~/scripts/lib/common.sh with the functions that repeat:

source lib/common.sh only works if the working directory is ~/scripts, and cron runs from $HOME. The canonical solution:

Taken apart from the inside out:

• ${BASH_SOURCE[0]} is the path of the file being read. It is used instead of $0 because if the file is loaded with source, $0 would be the parent script's, not its own. dirname extracts its directory, which may be relative.
• cd ... && pwd turns that relative path into an absolute one and resolves the .., all inside $( ), that is, in a subshell: your real working directory does not change. The && guarantees that if the cd fails the pwd is not run (SC2164 from 04-01).
• The comment # shellcheck source=... tells ShellCheck where the file is so that it can analyse it; without it, it warns with SC1091.

The ban on exit deserves a nuance: a library must not call it at its top level — that would kill the shell of whoever loads it with source, including your terminal — but it may do so inside a function whose declared purpose is to terminate, such as die(). The difference is who decides: not the library's author, but the caller.

On prefixes: in a project of your own, log and error are convenient and acceptable; in a library meant for others to load, prefix everything (tram_log, tram_error), because the day somebody loads your library and another one that also defines log, the last one read wins, silently. We already prefix the variables (TRAMONTANA_*), which is where the clash would be hardest to diagnose.

A library without tests is a library you will break without noticing. You do not need a framework: it is enough to run each function with known inputs and count the failures.

Thirty lines and you already have a safety net. The quiet log returns 0 case is not decorative: it checks the return 0 from section 6, the one that stops set -e killing the script when verbose mode is off. That is what tests are mainly good for: pinning down the subtle decisions before somebody "simplifies" them.

With the library ready, the header of health_check.sh and bookings_report.sh becomes identical and the duplicated functions disappear:

Three concrete gains. die 2 "..." replaces error ...; exit 2 in five places, so no error path can forget the exit. The threshold validation appears for the first time, and it appears because is_number already existed and using it cost one line. And TRAMONTANA_VERBOSE is a single variable in a single file, instead of four VERBOSEs that could drift out of sync. Add purge_releases.sh too: its run() moves into the library as it is, and its check of the active release becomes release_exists "$active" || die 66 "the active release does not exist".

• Forgetting local. The variable becomes global and tramples the caller's; with names such as i, tmp or line it is only a matter of time.
• local x=$(command) and believing you have checked the error. The exit code you see is local's, not the command's: always 0. Declare first (local x) and assign afterwards (x=$(command)). That is SC2155, and we will look at it in depth in 04-06.
• Expecting return to give back a piece of data. It only returns 0-255, and 300 becomes 44: data goes out on stdout. And beware of using the script's arguments inside a function: in there, $1 is the function's, so pass them with "$@". Define the function before using it, because Bash reads from top to bottom and the call would fail with command not found.
• Putting executable code at the top level of a library. Loading it will have effects nobody asked for, and an exit there will close the terminal of whoever loads it by hand. And do not load it with a relative path: it works in your terminal and fails in cron, which starts from another directory; use SCRIPT_DIR.
• Tip: document every function with three lines of contract — what it receives, what it prints, what it returns — right above it: that is what lets it be used without reading the body. And run test_common.sh before every commit of the library: ten seconds that stop you breaking four scripts at once.
• Tip: if a function needs more than five arguments or more than thirty lines, it is probably two functions.

Exercise 1. Explain what this fragment prints and why, then fix it so that it prints what its author expected.

Exercise 2. Add to lib/common.sh a function house_summary CSV HOUSE that prints house;bookings;nights;amount for one house from bookings.csv, with code 0 if it exists and 1 if not. Add two cases to test_common.sh: mas-figueres (must give mas-figueres;7;21;2450.00) and a non-existent house.

Exercise 3. Luis has written this library. Find the five problems and rewrite it.

Solution 1. It prints bookings: 25, and that is a lucky coincidence that hides two errors.

What happens: total inside process is not local, so the function tramples the caller's global variable; the sum 7+6+5+4+3 is 25 and that is what gets printed, not the 1000 assigned earlier. The return "$total" is also useless here and dangerous in general: if the bookings added up to 300, return would give back 44 (300 modulo 256) and whoever used it would get a false figure with no warning at all.

Now total keeps its value and the result arrives through its proper channel.

Solution 2.

The design respects the rules from section 9: the data goes out on stdout, the error on stderr, the return code distinguishes the cases, and the function neither calls exit nor assumes a working directory. awk printing nothing when there are no matches is what makes it possible to tell "does not exist" apart from "exists with zeros".

Solution 3. The five problems:

1. #!/bin/sh with function. Contradictory: dash does not know function. A library loaded with source carries a shebang by convention and for the editors, but it must not be executable.
2. echo "loading library..." at the top level. It does work when it is loaded and writes to stdout, contaminating the output of any script that uses it. A library loads in silence.
3. exit 1 inside the library. It kills the caller's script without giving it a choice, and if somebody loads it in their terminal, it closes it. The function should report and return a code.
4. No local, no inclusion guard and no documentation. usage is global and will trample any variable of the same name, loading the file twice redefines everything, and no function says what it returns.
5. ` `, $usage without quotes and LOGFILE fixed in /tmp. A predictable log file in /tmp is a classic security risk (04-06), and [ $usage -gt 80 ] fails if usage ends up empty.

Now whoever uses it decides: disk_above 80 || exit 0, or disk_above 80 && purge_releases.sh. The library reports, the script acts.

Your scripts have stopped repeating themselves, and along the way you have understood the two Bash oddities that most confuse people coming from other languages.

• You extract functions by the rule of three, because the block was asking for a comment or because there was a third level of nesting, and you name them so that the call reads like a sentence. You use the name() { ... } syntax, you define before you use, and you know that inside a function $1 and $@ are the function's, not the script's.
• You declare local on all function variables, and you understand that Bash has dynamic scope: what you declare is visible in the functions you call, with the invisible coupling that implies.
• You know that return only returns a code from 0 to 255 and you know the three real ways of returning data, with stdout by default and local -n prefixed with _ when needed.
• You write predicate functions with no explicit return, taking advantage of the fact that a function returns the code of its last statement, and you add return 0 when that last statement could legitimately fail. You know command and builtin for calling the original when you override a name, and the reason not to do it in a shared library.
• You have lib/common.sh with log(), error(), die(), require_command(), confirm() and format_bytes(), loaded with SCRIPT_DIR, protected by an inclusion guard, documented function by function and tested by test_common.sh.

And now an exercise in honesty. health_check.sh has carried set -euo pipefail since the first lesson and you have never seen exactly what it does. log() ends with a return 0 that has turned up twice "because otherwise the script dies", with no real explanation. bookings_report.sh creates the report's directory and, if something fails halfway, leaves it half written. And backup_tramontana.sh, promised since Module 2, still does not exist. The next lesson, Debugging and Error Handling, closes all of that: bash -x with a readable PS4, the shellcheck codes that matter most, strict mode pulled apart — including the five places where set -e does not work — trap with EXIT, ERR and INT so that no temporary file and no lock survives an interruption, idempotency as a design goal, and finally the complete, hardened backup script.