diff options
Diffstat (limited to 'doc/development/pry_debugging.md')
-rw-r--r-- | doc/development/pry_debugging.md | 130 |
1 files changed, 130 insertions, 0 deletions
diff --git a/doc/development/pry_debugging.md b/doc/development/pry_debugging.md new file mode 100644 index 00000000000..de5e1323e6a --- /dev/null +++ b/doc/development/pry_debugging.md @@ -0,0 +1,130 @@ +# Pry debugging + +## Invoking pry debugging + +To invoke the debugger, place `binding.pry` somewhere in your +code. When the Ruby interpreter hits that code, execution will stop, +and you can type in commands to debug the state of the program + +## `byebug` vs `binding.pry` + +`byebug` has a very similar interface as `gdb`, but `byebug` does not +use the powerful Pry REPL. + +`binding.pry` uses Pry, but lacks some of the `byebug` +features. GitLab uses the [`pry-byebug`](https://github.com/deivid-rodriguez/pry-byebug) +gem. This gem brings some capabilities `byebug` to `binding.pry`, so +using that, will give you the most debugging powers. + +## `byebug` + +Check out [the docs](https://github.com/deivid-rodriguez/byebug) for the full list of commands. + +You can start the Pry REPL with the `pry` command. + +## `pry` + +There are **a lot** of features present in `pry`, too much to cover in +this document, so for the full documentation head over to the [Pry wiki](https://github.com/pry/pry/wiki). + +Below are a few features definitely worth checking out, also run +`help` in a pry session to see what else you can do. + +### State navigation + +With the [state navigation](https://github.com/pry/pry/wiki/State-navigation) +you can move around in the code to discover methods and such: + +```ruby +# Change context +[1] pry(main)> cd Pry +[2] pry(Pry):1> + +# Print methods +[2] pry(Pry):1> ls -m + +# Find a method +[3] pry(Pry):1> find-method to_yaml +``` + +### Source browsing + +You [look at the source code](https://github.com/pry/pry/wiki/Source-browsing) +from your `pry` session: + +```ruby +[1] pry(main)> $ Array#first +# The above is equivalent to +[2] pry(main)> cd Array +[3] pry(Array):1> show-source first +``` + +`$` is an alias for `show-source`. + +### Documentation browsing + +Similar to source browsing, is [Documentation browsing](https://github.com/pry/pry/wiki/Documentation-browsing). + +```ruby +[1] pry(main)> show-doc Array#first +``` + +`?` is an alias for `show-doc`. + +### Command history + +With <kdb>Ctrl+R</kbd> you can search your [command history](https://github.com/pry/pry/wiki/History). + +## Stepping + +To step through the code, you can use the following commands: + +- `break`: Manage breakpoints. +- `step`: Step execution into the next line or method. Takes an + optional numeric argument to step multiple times. +- `next`: Step over to the next line within the same frame. Also takes + an optional numeric argument to step multiple lines. +- `finish`: Execute until current stack frame returns. +- `continue`: Continue program execution and end the Pry session. + +## Callstack navigation + +You also can move around in the callstack with these commands: + +- `backtrace`: Shows the current stack. You can use the numbers on the + left side with the frame command to navigate the stack. +- `up`: Moves the stack frame up. Takes an optional numeric argument + to move multiple frames. +- `down`: Moves the stack frame down. Takes an optional numeric + argument to move multiple frames. +- `frame <n>`: Moves to a specific frame. Called without arguments + will show the current frame. + +## Short commands + +When you use `binding.pry` instead of `byebug`, the short commands +like `s`, `n`, `f`, and `c` do not work. To reinstall them, add this +to `~/.pryrc`: + +```ruby +if defined?(PryByebug) + Pry.commands.alias_command 's', 'step' + Pry.commands.alias_command 'n', 'next' + Pry.commands.alias_command 'f', 'finish' + Pry.commands.alias_command 'c', 'continue' +end +``` + +## Repeat last command + +You can repeat the last command by just hitting the <kbd>Enter</kbd> +key (e.g., with `step` or`next`), if you place the following snippet +in your `~/.pryrc`: + +```ruby +Pry::Commands.command /^$/, "repeat last command" do + _pry_.run_command Pry.history.to_a.last +end +``` + +`byebug` supports this out-of-the-box. |