How to Debug Bash Scripts

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 -x where 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.

Comments

Dennis Roberts
Dennis Roberts's gravatar

I liked your write up. I have been using Linux for the last 10 years and not a day goes by that I don't learn something new. The PS4 is new to me. I also like your log function.


Posted at 5:20 a.m. on August 25, 2009

Anonymous
Anonymous's gravatar

Today is 2009-08-25


Posted at 8:30 a.m. on August 25, 2009

Anonymous
Anonymous's gravatar

Excellent - thanks!

  • Andre.

Posted at 9:19 a.m. on August 25, 2009

Abdul Fattah
Abdul Fattah's gravatar

Thanks Ayman, very useful tips :)


Posted at 10:48 a.m. on August 25, 2009

Anonymous
Anonymous's gravatar

I'd highly recommend all your bash scripts start off by:

set -e

This will abort the rest of the script if any of the commands you run return non-0. This will help find and avoid what would have otherwise been silent lurking problems.


Posted at 11:12 a.m. on August 25, 2009

decasm
decasm's gravatar

The logging function you have there is good, but for larger projects, log4sh might be best.


Posted at 1:19 p.m. on August 25, 2009

Drew
Drew's gravatar

Vivid articles. thinks


Posted at 2:08 p.m. on August 25, 2009

Marko
Marko's gravatar

Hey Ayman, thanks a lot! I'm still fairly new to bash scripting and there some really nice tips here...


Posted at 6:17 p.m. on August 25, 2009

omid8bimo
omid8bimo's gravatar

cool notes dude :) pretty useful


Posted at 6:57 p.m. on August 25, 2009

Ayman Hourieh
Ayman Hourieh's gravatar

Thanks for your comment. Glad to know that you found it useful.


Posted at 7:09 p.m. on August 25, 2009

Ayman Hourieh
Ayman Hourieh's gravatar

"set -o x" is the short form of "set -o xtrace".


Posted at 7:11 p.m. on August 25, 2009

Thell
Thell's gravatar

Your sharing this info is greatly appreciated.

That PS4 was just what the doctor ordered.

It has been added to:: http://mywiki.wooledge.org/BashGuide/Practices/Debugging


Posted at 4:47 p.m. on September 3, 2009

missnoerrors
missnoerrors's gravatar

Useful and concise info and comments. Thanks! set -e is what I was looking for to control build script, now it'll get a logging upgrade too!


Posted at 4:58 a.m. on October 3, 2009

Polprav
Polprav's gravatar

Hello from Russia! Can I quote a post in your blog with the link to you?


Posted at 2:06 p.m. on October 20, 2009

Post a comment

HTML is not allowed. You can use markdown syntax to format your comment.