Make your Ruby backtrace pretty again. Just require pretty_trace/enable in your ruby script, and errors will become clearer and more readable.

Install

$ gem install pretty_trace

Or with bundler:

# Just install, do not activate
gem 'pretty_trace'

# Or, install and enable
gem 'pretty_trace', require: 'pretty_trace/enable'

# Or, install, enable and enable trimming
gem 'pretty_trace', require: 'pretty_trace/enable-trim'

Example

Create this ruby file:

# test.rb
require "pretty_trace/enable-trim"
require "fileutils"
FileUtils.rm 'no_such_file'

Run it:

Usage

The easiest way to use Pretty Trace is to require its activation script in your script:

require 'pretty_trace/enable'

From this point on, any exception will be formatted.

If you wish to show a trimmed version of the backtrace (where errors from the same file are collapsed into one line), require this script instead:

require 'pretty_trace/enable-trim'

If you prefer to have more control, you can configure these settings manually:

require 'pretty_trace'

# Exceptions here will not be formatted

PrettyTrace.enable
# Exceptions here will be formatted

PrettyTrace.disable
# Exceptions here will not be formatted

PrettyTrace.enable
PrettyTrace.trim
# Exceptions here will be formatted and trimmed

PrettyTrace.no_trim
# Exceptions here will not be trimmed

Configuration

Filtering specific paths

To filter out lines in the backtrace, use PrettyTrace.filter. This method accepts a single regular expression, or an array of regular expressions.

Note that you can call this method several times, and it will aggregate all your filters together.

require 'pretty_trace/enable'
PrettyTrace.filter /rails/
PrettyTrace.filter [/gem/, /lib/]

If you wish to temporarily disable Pretty Trace (for example, when you need to see the full trace paths), you can set the environment variable PRETTY_TRACE=off before running your script:

$ PRETTY_TRACE=off ruby myscript.rb

If you wish to temporarily disable trimming and filtering, you can set the environment variable PRETTY_TRACE=full before running your script:

$ PRETTY_TRACE=full ruby myscript.rb

Showing a debug tip

If you wish to see a debug tip, reminding you to set PRETTY_TRACE to full or off when an error occurs, use PrettyTrace.debug_tip:

require 'pretty_trace/enable'
PrettyTrace.debug_tip     # enable debug tip
PrettyTrace.no_debug_tip  # disable debug tip

Contributing / Support

If you experience any issue, have a question or a suggestion, or if you wish to contribute, feel free to open an issue.