đŸȘŽ Anil's Garden

Bash best practices cheat-sheets

02 Apr 20256 min read

Bash best practices | cheat-sheets

Excerpt

Cheat sheets for various stuff

cheat-sheets

Cheat sheets for various stuff

View the Project on GitHub bertvv/cheat-sheets

An attempt to bring order in good advice on writing Bash scripts I collected from several sources.

General

  • The principles of Clean Code apply to Bash as well

  • Always use long parameter notation when available. This makes the script more readable, especially for lesser known/used commands that you don’t remember all the options for.

      <span># Avoid:</span>
  <span>rm</span> <span>-rf</span> <span>--</span> <span>"</span><span>${</span><span>dir</span><span>}</span><span>"</span>

  <span># Good:</span>
  <span>rm</span> <span>--recursive</span> <span>--force</span> <span>--</span> <span>"</span><span>${</span><span>dir</span><span>}</span><span>"</span>

  • Don’t use:

    but

    pushd and popd may also be useful:

      <span>pushd</span> <span>"</span><span>${</span><span>foo</span><span>}</span><span>"</span>
  <span>[</span>...]
  <span>popd</span>

  • Use nohup foo | cat & if foo must be started from a terminal and run in the background.

Variables

  • Prefer local variables within functions over global variables
  • If you need global variables, make them readonly
  • Variables should always be referred to in the ${var} form (as opposed to $var.
  • Variables should always be quoted, especially if their value may contain a whitespace or separator character: "${var}"
  • Capitalization:
    • Environment (exported) variables: ${ALL_CAPS}
    • Local variables: ${lower_case}
  • Positional parameters of the script should be checked, those of functions should not
  • Some loops happen in subprocesses, so don’t be surprised when setting variabless does nothing after them. Use stdout and greping to communicate status.

Substitution

  • Always use $(cmd) for command substitution (as opposed to backquotes)

  • Prepend a command with \ to override alias/builtin lookup. E.g.:

    $ \time bash -c "dnf list installed | wc -l" 5466 1.32user 0.12system 0:01.45elapsed 99%CPU (0avgtext+0avgdata 97596maxresident)k 0inputs+136outputs (0major+37743minor)pagefaults 0swaps

Output and redirection

  • For various reasons, printf is preferable to echo. printf gives more control over the output, it’s more portable and its behaviour is defined better.

  • Print error messages on stderr. E.g., I use the following function:

      error<span>()</span> <span>{</span>
    <span>printf</span> <span>"</span><span>${</span><span>red</span><span>}</span><span>!!! %s</span><span>${</span><span>reset</span><span>}</span><span>\\</span><span>n"</span> <span>"</span><span>${</span><span>*</span><span>}</span><span>"</span> 1&gt;&amp;2
  <span>}</span>

  • Name heredoc tags with what they’re part of, like:

      <span>cat</span> <span>&lt;&lt;</span><span>HELPMSG</span><span>
  usage </span><span>$0</span><span> [OPTION]... [ARGUMENT]...
</span><span>
  HELPMSG
</span>

  • Single-quote heredocs leading tag to prevent interpolation of text between them.

  • When combining a sudo command with redirection, it’s important to realize that the root permissions only apply to the command, not to the part after the redirection operator. An example where a script needs to write to a file that’s only writeable as root:

      <span># this won't work:</span>
  <span>sudo printf</span> <span>"..."</span> <span>&gt;</span> /root/some_file

  <span># this will:</span>
  <span>printf</span> <span>"..."</span> | <span>sudo tee</span> /root/some_file <span>&gt;</span> /dev/null

Functions

Bash can be hard to read and interpret. Using functions can greatly improve readability. Principles from Clean Code apply here.

  • Apply the Single Responsibility Principle: a function does one thing.

  • Don’t mix levels of abstraction

  • Describe the usage of each function: number of arguments, return value, output

  • Declare variables with a meaningful name for positional parameters of functions

      foo<span>()</span> <span>{</span>
    <span>local </span><span>first_arg</span><span>=</span><span>"</span><span>${</span><span>1</span><span>}</span><span>"</span>
    <span>local </span><span>second_arg</span><span>=</span><span>"</span><span>${</span><span>2</span><span>}</span><span>"</span>
    <span>[</span>...]
  <span>}</span>

  • Create functions with a meaningful name for complex tests

      <span># Don't do this</span>
  <span>if</span> <span>[</span> <span>"$#"</span> <span>-ge</span> <span>"1"</span> <span>]</span> <span>&amp;&amp;</span> <span>[</span> <span>"</span><span>$1</span><span>"</span> <span>=</span> <span>'-h'</span> <span>]</span> <span>||</span> <span>[</span> <span>"</span><span>$1</span><span>"</span> <span>=</span> <span>'--help'</span> <span>]</span> <span>||</span> <span>[</span> <span>"</span><span>$1</span><span>"</span> <span>=</span> <span>"-?"</span> <span>]</span><span>;</span> <span>then
    </span>usage
    <span>exit </span>0
  <span>fi</span>

  <span># Do this</span>
  help_wanted<span>()</span> <span>{</span>
    <span>[</span> <span>"$#"</span> <span>-ge</span> <span>"1"</span> <span>]</span> <span>&amp;&amp;</span> <span>[</span> <span>"</span><span>$1</span><span>"</span> <span>=</span> <span>'-h'</span> <span>]</span> <span>||</span> <span>[</span> <span>"</span><span>$1</span><span>"</span> <span>=</span> <span>'--help'</span> <span>]</span> <span>||</span> <span>[</span> <span>"</span><span>$1</span><span>"</span> <span>=</span> <span>"-?"</span> <span>]</span>
  <span>}</span>

  <span>if </span>help_wanted <span>"</span><span>$@</span><span>"</span><span>;</span> <span>then
    </span>usage
    <span>exit </span>0
  <span>fi</span>

Cleanup code

An idiom for tasks that need to be done before the script ends (e.g. removing temporary files, etc.). The exit status of the script is the status of the last statement before the finish function.

finish<span>()</span> <span>{</span>
  <span>result</span><span>=</span><span>$?</span>
  <span># Your cleanup code here</span>
  <span>exit</span> <span>${</span><span>result</span><span>}</span>
<span>}</span>
<span>trap </span>finish EXIT ERR

Source: Aaron Maxwell, How “Exit Traps” can make your Bash scripts way more robust and reliable.

Writing robust scripts and debugging

Bash is not very easy to debug. There’s no built-in debugger like you have with other programming languages. By default, undefined variables are interpreted as empty strings, which can cause problems further down the line. A few tips that may help:

  • Always check for syntax errors by running the script with bash -n myscript.sh

  • Use ShellCheck and fix all warnings. This is a static code analyzer that can find a lot of common bugs in shell scripts. Integrate ShellCheck in your text editor (e.g. Syntastic plugin in Vim)

  • Abort the script on errors and undbound variables. Put the following code at the beginning of each script.

      <span>set</span> <span>-o</span> errexit   <span># abort on nonzero exitstatus</span>
  <span>set</span> <span>-o</span> nounset   <span># abort on unbound variable</span>
  <span>set</span> <span>-o</span> pipefail  <span># don't hide errors within pipes</span>

    A shorter version is shown below, but writing it out makes the script more readable.

  • Use Bash’s debug output feature. This will print each statement after applying all forms of substitution (parameter/command substitution, brace expansion, globbing, etc.)

    • Run the script with bash -x myscript.sh
    • Put set -x at the top of the script
    • If you only want debug output in a specific section of the script, put set -x before and set +x after the section.

  • Write lots of log messages to stdout or stderr so it’s easier to drill down to what part of the script contains problematic code. I have defined a few functions for logging, you can find them in my dotfiles repository.

  • Use bashdb

Shell script template

An annotated template for Bash shell scripts:

For now, see https://github.com/bertvv/dotfiles/blob/master/.vim/templates/sh

Resources

Templates

Portable shell scripts

Fun

Graph View

Backlinks

  • No backlinks found