ruby/debug cheatsheet


3 min read

This cheatsheet can help you get started with ruby/debug as well as use it in your daily development. It's not an exhausting list of its features or commands, so please go through its document as well.

If you're migrating from byebug, I also recommend checking my byebug to ruby/debug migration guide.

I also shared how to build a powerful debugging workflow with it in my talk: ruby/debug - The best investment for your productivity.

Getting Started

  1. Add gem "debug" to your Gemfile
  2. Run bundle install
  3. Add require "debug"
  4. Use binding.b or debugger to set initial breakpoints (they're same)

The rdbg Executable

(Running with bundle exec is usually recommended)

Debug a Ruby script with executable$ rdbg foo.rb
Debug a Ruby command with executable$ rdbg -c -- bundle exec <cmd>
Debug without the initial stop$ rdbg -n ...

Need Any Help?

See document of all the commandsh[elp]
See document of <cmd>h[elp] <cmd>
See configurationsconfig
Learn how to configure the debuggerh config

Step Debugging & Frame Navigation

Step ins[tep]
Step overn[ext]
Move to <id> framef[rame] <id>
Move up a frameup
Move down a framedown
Continue the programc[ontinue]
Quit the debuggerq[uit]!
Kill the programkill

Breakpoint Commands

Setting Breakpoints

A lineb[reak] <line>
A file:lineb[reak] <file>:<line>
An instance methodb[reak] <class>#<method>
An object's methodb[reak] <obj>.<method>
A class methodb[reak] <class>.<method>
An exceptioncatch <ExceptionClass>
Mutation of instance variablewatch <@ivar>

Options (applies to all 3 breakpoint commands)

Condition TypeOption
With an if condition... if: <expr>
With a path condition... path: /path/
To run a command and continue... do: <cmd>
To run a command before stopping... pre: <cmd>

Managing Breakpoints

List all breakpointsb[reak]
Delete a breakpointdel[ete] <id>
Delete all breakpointsdel[ete]

Information Commands

Current scope's outlne (methods and avialble ivars, locals)ls
obj's outlne (methods and avialble ivars, locals)ls obj
Only <n> backtracebt <n>
Source codel[ist]
Local variables, instance variables, and current scope's constantsi[nfo]
Local varibalesi[nfo] l
Instance variablesi[nfo] i
Global varibalesi[nfo] g
Constantsi[nfo] c
Filter variables/constants by namesi[nfo] ... /regexp/

Scriptable Breakpoints

Run the <cmd> and stop the programbinding.b(pre: "<cmd>")
Run the <cmd> and continue the programbinding.b(do: "<cmd>")
Run multiple commandsbinding.b(do: "<cmd1> ;; <cmd2>")

My Favourites

Glance through variables before I start typingbinding.b(pre: "i")
Quickly get the surrounding contextbinding.b(pre: "ls ;; bt 10")
Start tracing exceptionsbinding.b(do: "trace exception")
Stop me when there's an exceptionbinding.b(do: "catch StandardError")