Commit 8895863c authored by Sean McGivern's avatar Sean McGivern

Merge branch 'tc-pry-docs' into 'master'

First version of pry_debugging.md

Closes #45728

See merge request gitlab-org/gitlab-ce!20740
parents 256e7a63 13afac65
...@@ -40,6 +40,7 @@ description: 'Learn how to contribute to GitLab.' ...@@ -40,6 +40,7 @@ description: 'Learn how to contribute to GitLab.'
- [View sent emails or preview mailers](emails.md) - [View sent emails or preview mailers](emails.md)
- [Shell commands](shell_commands.md) in the GitLab codebase - [Shell commands](shell_commands.md) in the GitLab codebase
- [`Gemfile` guidelines](gemfile.md) - [`Gemfile` guidelines](gemfile.md)
- [Pry debugging](pry_debugging.md)
- [Sidekiq debugging](sidekiq_debugging.md) - [Sidekiq debugging](sidekiq_debugging.md)
- [Gotchas](gotchas.md) to avoid - [Gotchas](gotchas.md) to avoid
- [Avoid modules with instance variables](module_with_instance_variables.md) if possible - [Avoid modules with instance variables](module_with_instance_variables.md) if possible
......
# 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.
...@@ -101,7 +101,7 @@ CHROME_HEADLESS=0 bundle exec rspec some_spec.rb ...@@ -101,7 +101,7 @@ CHROME_HEADLESS=0 bundle exec rspec some_spec.rb
The test will go by quickly, but this will give you an idea of what's happening. The test will go by quickly, but this will give you an idea of what's happening.
You can also add `byebug` or `binding.pry` to pause execution and step through You can also add `byebug` or `binding.pry` to pause execution and [step through](../pry_debugging.md#stepping)
the test. the test.
#### Screenshots #### Screenshots
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment