From 13afac6533170ad1ca966b4da09910aa23a81328 Mon Sep 17 00:00:00 2001 From: Toon Claes Date: Fri, 20 Jul 2018 07:31:51 +0200 Subject: First version of pry_debugging.md --- doc/development/README.md | 1 + doc/development/pry_debugging.md | 130 ++++++++++++++++++++++++ doc/development/testing_guide/best_practices.md | 2 +- 3 files changed, 132 insertions(+), 1 deletion(-) create mode 100644 doc/development/pry_debugging.md diff --git a/doc/development/README.md b/doc/development/README.md index 5d6fed5bc72..fed3903c771 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -40,6 +40,7 @@ description: 'Learn how to contribute to GitLab.' - [View sent emails or preview mailers](emails.md) - [Shell commands](shell_commands.md) in the GitLab codebase - [`Gemfile` guidelines](gemfile.md) +- [Pry debugging](pry_debugging.md) - [Sidekiq debugging](sidekiq_debugging.md) - [Gotchas](gotchas.md) to avoid - [Avoid modules with instance variables](module_with_instance_variables.md) if possible 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 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 `: 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 Enter +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. diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index 1a926a660f1..acbfa1850b4 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -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. -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. #### Screenshots -- cgit v1.2.1