How to Debug Bash Scripts

Article by Ayman Hourieh, already published on his Blog

Bash is the default scripting language in most Linux systems. Its usage ranges from an interactive command interpreter to a scripting language for writing complex programs. Debugging facilities are a standard feature of compilers and interpreters, and bash is no different in this regard. In this article, I will explain various techniques and tips for debugging Bash scripts.

Tracing script execution

You can instruct Bash to print debugging output as it interprets you scripts. When running in this mode, Bash prints commands and their arguments before they are executed.

To see how this works, let’s try it on an example script. The following simple script greets the user and prints the current date:

#!/bin/bash
echo "Hello $USER,"
echo "Today is $(date +'%Y-%m-%d')"

To trace the execution of the script, use bash -x to run it:

$ bash -x example_script.sh
+ echo 'Hello ayman,'
Hello ayman,
++ date +%Y-%m-%d
+ echo 'Today is 2009-08-24'
Today is 2009-08-24

In this mode, Bash prints each command (with its expanded arguments) before executing it. Debugging output is prefixed with a number of + signs to indicate nesting. This output helps you see exactly what the script is doing, and understand why it is not behaving as expected.

Adding line numbers to tracing output

In large scripts, it may be helpful to prefix this debugging output with the script name, line number and function name. You can do this by setting the following environment variable:

export PS4='+${BASH_SOURCE}:${LINENO}:${FUNCNAME[0]}: '

Let’s trace our example script again to see the new debugging output:

$ bash -x example_script.sh
+example_script.sh:2:: echo 'Hello ayman,'
Hello ayman,
++example_script.sh:3:: date +%Y-%m-%d
+example_script.sh:3:: echo 'Today is 2009-08-24'
Today is 2009-08-24

Tracing part of a script

Sometimes, you are only interested in tracing one part of your script. This can be done by calling set -xwhere you want to enable tracing, and calling set +x to disable it. Let’s apply this to our example script:

#!/bin/bash
echo "Hello $USER,"
set -x
echo "Today is $(date %Y-%m-%d)"
set +x

Now, let’s run the script:

$ ./example_script.sh
Hello ayman,
++example_script.sh:4:: date +%Y-%m-%d
+example_script.sh:4:: echo 'Today is 2009-08-24'
Today is 2009-08-24
+example_script.sh:5:: set +x

Notice that we no longer need to run the script with bash -x.

Logging

Tracing script execution is sometimes too verbose, especially if you are only interested in a limited number of events, like calling a certain function or entering a certain loop. In this case, it’s better to log the events you are interested in. Logging can be achieved with something as simple as a function that prints a string to stderr:

_log() {
  if [ "$_DEBUG" == "true" ]; then
    echo 1>&2 "$@"
  fi
}

Now you can embed logging messages into your script by calling this function:

_log "Copying files..."
cp src/* dst/

Log messages are printed only if the _DEBUG variable is set to true. This allows you to toggle the printing of log messages depending on your needs. You don’t need to modify your script in order to change this variable; you can set it on the command line:

$ _DEBUG=true ./example_script.sh

Using the Bash debugger

If you are writing a complex script and you need a full-fledged debugger to debug it, then you can use bashdb, the Bash debugger. The debugger contains all the features that you would expect, like breakpoints, stepping in and out of functions, and attaching to running scripts. Its interface is a bit similar to gdb. You can read the documentation of bashdb for more information.