Skip to content

History

Jump to bottom
Simon Perepelitsa edited this page Feb 22, 2023 · 15 revisions
Clone this wiki locally

Managing History

Quick Menu:

Back to Main Menu

Overview

The ability to control history is a useful feature in itself, but it becomes indispensable when your REPL sessions become large or complicated. As a result, Pry provides rich history management, enabling you to load, save, view, and replay history, among other things.

The history file

As stated in the customization section the Pry.config.history_file option can be used to set the history file - the file where history is saved to and loaded from.

Note that because both the .pryrc file and plugins are loaded before the history file, you can change the history options in either of these places. You can also change it any point before you start Pry when invoking it at runtime.

The default history file is ~/.pry_history or ~/.local/share/pry/pry_history

Example: Use irb's history file instead

Pry.config.history_file = "~/.irb_history"

Back to top

Loading history

The Pry.config.history_load option determines whether history will be loaded from the history file when a Pry session starts. This option can be modified in any of the places given in the history file section, above.

Loading history will pre-populate the Readline::HISTORY array with the content in the history file.

The default value is true

Example: Disable history loading

Pry.config.history_load = false

Back to top

Saving history

The Pry.config.history_save option determines whether history will be saved to the history file when a Pry session ends. This option can be modified in any of the places given in the history file section, above.

The default value is true

Example: Disable history saving

Pry.config.history_save = false

Back to top

The hist command (overview)

The hist command is the primary interface to your Pry history. The hist command enables you to view, search, and replay history, among other things.

Note however that the current version of the hist command does not allow options to stack; that is hist --tail 10 --grep hello does not perform as expected. This feature will be added in a future version.

The hist command when invoked by itself with no options will simply display all Pry history. If there is more than a screenful of history the output will be sent through a pager.

Example: Display all Pry history

pry(main)> hist
0: require 'bacon'
1: $ describe
2: ? describe
3: ls -M Bacon::Context
4: hist

Back to top

The grep option

When the --grep REGEX option is passed to hist only those lines which match the regular expression will be displayed.

pry(main)> hist --grep desc
1: $ describe
2: ? describe

Back to top

The tail option

When the --tail N option is passed to hist only the last N lines of history will be displayed. Note that if the N parameter is left out then hist will default to displaying the last 10 lines.

Example:

pry(main) hist --tail 5
12:     puts "silk banners, drove of pure lilies"
13:     puts "beneath walls a virgin once defended;"
14:   end
14: end
15: hist --tail 5

Back to top

The head option

When the --head N option is passed to hist only the first N lines of history will be displayed. Note that if the N parameter is left out then hist will default to displaying the first 10 lines.

Example:

pry(main)> hist --head 3
0: require 'bacon'
1: $ describe
2: ? describe

Back to top

The no-numbers option

The --no-numbers (or -n) switch turns off line numbers when displaying readline history. This can be useful as an alternative to --replay as it enables easy copy/pasting of history back into Pry for replaying.

[8] (pry) main: 0> hist -n -T
hist -n
hist -T -n
.clear
hist -n -T
def hello
  puts "hi"
end
(1..3).each do |v|
  puts v * 6
end
[9] (pry) main: 0>

Back to top

The replay option

The --replay A..B option allows us to replay lines of history. It accepts either a single line number or a range of numbers. It even allows replaying of incomplete multi line expressions.

Example:

pry(main)> hist --tail 3
7000: puts "hello world";
7001: puts "good evening world";
7002: hist --tail 3
pry(main)> hist --replay 7000
hello world

Example: Replaying an incomplete multi-line expression

pry(main)> hist --tail 6
7008: class Evening
7009:   def sundown
7010:     puts "goodnight"
7011:   end
7012: end
7013: hist --tail 6
pry(main)> hist --replay 7008..7011
pry(main)*   def moonout
pry(main)*     puts "dog's bark"
pry(main)*   end
pry(main)* end;
pry(main)> Evening.new.moonout;
dog's bark
pry(main)>

Back to top

The exclude-pry option

The --exclude-pry option, or -e, displays all lines of history except those that are Pry commands.

Example: Comparision of hist with and without --exclude-pry

pry(main)> hist
0: hist
1: ls -m
2: show-method Gem.ruby
3: hist
4: puts "testing: 1, 2, 3..."
5: 1 + 3
6: hist
pry(main)> hist --exclude-pry
4: puts "testing: 1, 2, 3..."
5: 1 + 3
pry(main)>

Back to top

The save option

The --save [A..B] FILE option allows you to save lines from the history buffer to a file. If the range is left out the entire history is saved to the specified file. Note that an implied --exclude is performed on the lines before saving -- only valid Ruby code is saved.

Example:

pry(main)> hist
0: hist
1: ls -m
2: show-method Gem.ruby
3: hist
4: puts "testing: 1, 2, 3..."
5: 1 + 3
6: hist
7: hist --exclude
8: hist -h
9: hist
pry(main)> hist --save 4..5 test.rb
Saving history in /Users/john/ruby/projects/pry.wiki/test.rb ...
... history saved.
pry(main)> cat test.rb
puts "testing: 1, 2, 3..."
1 + 3
pry(main)>

Back to top

The show option

The --show A..B options displays the line or range of lines to the user. May be useful when used after the --grep option and before the --replay option.

Example:

pry(main)> hist --show 2..5
2: show-method Gem.ruby
3: hist
4: puts "testing: 1, 2, 3..."
5: 1 + 3
pry(main)>

Back to top

The clear option

The --clear option clears all current session history.

Example:

pry(main)> hist --clear
History cleared.
pry(main)> hist
0: hist
pry(main)>

Back to top