Skip to content

Commit df13097

Browse files
committed
docs: Add POSIX (non-Bash4) exceptions to Bash coding guide
1 parent 44035ab commit df13097

1 file changed

Lines changed: 28 additions & 3 deletions

File tree

_docs/reference/bash-styles.adoc

Lines changed: 28 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,30 @@ See also {xref_docs_cli-styles_link} for guidance specific to command-line inter
1717
[[file-and-script-structure]]
1818
== File and Script Structure
1919

20+
With certain exceptions, shell scripting is done in Bash 4.
21+
22+
We will start with the exceptions.
23+
24+
[[posix-compliant]]
25+
=== POSIX Compliant Scripts
26+
27+
Scripts that require maximum portability and compatibility should use the POSIX-compliant `sh` shell and avoid Bash-specific features.
28+
29+
These scripts must begin with the shebang `#!/bin/sh` and should be tested in a POSIX-compliant environment to ensure they do not rely on Bash extensions.
30+
31+
This standard is mainly to cover MacOS systems, which do not support Bash 4 out of the box.
32+
Therefore, bootstrap/installer scripts will need to be executable in a Bash 3 environment, where they can prompt for Bash 4 installation if it is not detected and if it is needed by a follow-on script.
33+
34+
Such files should begin with:
35+
36+
[source,shell]
37+
----
38+
#!/bin/sh
39+
# shellcheck shell=sh
40+
----
41+
42+
The rest of this guide focuses on Bash 4 scripts, which are the norm for DocOps Lab projects and products that use basic shell scripts.
43+
2044
[[bash-version]]
2145
=== Bash Version (4.0)
2246

@@ -41,8 +65,8 @@ Keep it compact: one line per thought, no visual padding.
4165
[source,bash]
4266
----
4367
#!/usr/bin/env bash
44-
# script-name: brief description of what the script does.
45-
# Depends on: curl, jq
68+
# script-name.sh: brief description of what the script does.
69+
# Requires: curl, jq
4670
----
4771

4872
[[indentation]]
@@ -175,7 +199,7 @@ Use `snake_case` and `local` declaration.
175199

176200
Operation functions::
177201
The substantive work of a script; what `cmd_` functions orchestrate, and what sourced libraries export as their callable API.
178-
Use unprefixed `snake_case`.
202+
Use un-prefixed `snake_case`.
179203
* `evaluate_system()`, `build_docker_image()`, `get_current_version()`
180204

181205
Helper functions::
@@ -449,6 +473,7 @@ Add a comment explaining the intent.
449473
docker build ${docker_args} -t "${image}" .
450474
----
451475

476+
452477
[[output]]
453478
== Output
454479

0 commit comments

Comments
 (0)