gitlab-org--gitlab-foss/doc/development/pry_debugging.md
Evan Read d05eebe1dd Fix most bare URLs in project
Linting rule not enabled for now
because tooling produces false
positives.
2019-07-02 08:50:00 +00:00

130 lines
3.7 KiB
Markdown

# 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 **Ctrl+R** 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.