1---
2stage: none
3group: unassigned
4info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
5---
6
7# Pry debugging
8
9## Invoking pry debugging
10
11To invoke the debugger, place `binding.pry` somewhere in your
12code. When the Ruby interpreter hits that code, execution stops,
13and you can type in commands to debug the state of the program.
14
15When debugging code in another process like Puma or Sidekiq, you can use `binding.pry_shell`.
16You can then connect to this session by using the [pry-shell](https://github.com/meinac/pry-shell) executable.
17You can watch [this video](https://www.youtube.com/watch?v=Lzs_PL_BySo), for more information about
18how to use the `pry-shell`.
19
20## `byebug` vs `binding.pry`
21
22`byebug` has a very similar interface as `gdb`, but `byebug` does not
23use the powerful Pry REPL.
24
25`binding.pry` uses Pry, but lacks some of the `byebug`
26features. GitLab uses the [`pry-byebug`](https://github.com/deivid-rodriguez/pry-byebug)
27gem. This gem brings some capabilities `byebug` to `binding.pry`, so
28using that gives you the most debugging powers.
29
30## `byebug`
31
32Check out [the docs](https://github.com/deivid-rodriguez/byebug) for the full list of commands.
33
34You can start the Pry REPL with the `pry` command.
35
36## `pry`
37
38There are **a lot** of features present in `pry`, too much to cover in
39this document, so for the full documentation head over to the [Pry wiki](https://github.com/pry/pry/wiki).
40
41Below are a few features definitely worth checking out, also run
42`help` in a pry session to see what else you can do.
43
44### State navigation
45
46With the [state navigation](https://github.com/pry/pry/wiki/State-navigation)
47you can move around in the code to discover methods and such:
48
49```ruby
50# Change context
51[1] pry(main)> cd Pry
52[2] pry(Pry):1>
53
54# Print methods
55[2] pry(Pry):1> ls -m
56
57# Find a method
58[3] pry(Pry):1> find-method to_yaml
59```
60
61### Source browsing
62
63You [look at the source code](https://github.com/pry/pry/wiki/Source-browsing)
64from your `pry` session:
65
66```ruby
67[1] pry(main)> $ Array#first
68# The above is equivalent to
69[2] pry(main)> cd Array
70[3] pry(Array):1> show-source first
71```
72
73`$` is an alias for `show-source`.
74
75### Documentation browsing
76
77Similar to source browsing, is [Documentation browsing](https://github.com/pry/pry/wiki/Documentation-browsing).
78
79```ruby
80[1] pry(main)> show-doc Array#first
81```
82
83`?` is an alias for `show-doc`.
84
85### Command history
86
87With <kbd>Control</kbd> + <kbd>R</kbd> you can search your [command history](https://github.com/pry/pry/wiki/History).
88
89## Stepping
90
91To step through the code, you can use the following commands:
92
93- `break`: Manage breakpoints.
94- `step`: Step execution into the next line or method. Takes an
95  optional numeric argument to step multiple times.
96- `next`: Step over to the next line within the same frame. Also takes
97  an optional numeric argument to step multiple lines.
98- `finish`: Execute until current stack frame returns.
99- `continue`: Continue program execution and end the Pry session.
100
101## Callstack navigation
102
103You also can move around in the callstack with these commands:
104
105- `backtrace`: Shows the current stack. You can use the numbers on the
106  left side with the frame command to navigate the stack.
107- `up`: Moves the stack frame up. Takes an optional numeric argument
108  to move multiple frames.
109- `down`: Moves the stack frame down. Takes an optional numeric
110  argument to move multiple frames.
111- `frame <n>`: Moves to a specific frame. Called without arguments
112  displays the current frame.
113
114## Short commands
115
116When you use `binding.pry` instead of `byebug`, the short commands
117like `s`, `n`, `f`, and `c` do not work. To reinstall them, add this
118to `~/.pryrc`:
119
120```ruby
121if defined?(PryByebug)
122  Pry.commands.alias_command 's', 'step'
123  Pry.commands.alias_command 'n', 'next'
124  Pry.commands.alias_command 'f', 'finish'
125  Pry.commands.alias_command 'c', 'continue'
126end
127```
128
129## Repeat last command
130
131You can repeat the last command by just hitting the <kbd>Enter</kbd>
132key (for example, with `step` or`next`), if you place the following snippet
133in your `~/.pryrc`:
134
135```ruby
136Pry::Commands.command /^$/, "repeat last command" do
137  _pry_.run_command Pry.history.to_a.last
138end
139```
140
141`byebug` supports this out-of-the-box.
142