Configure IRB

Configuration Sources

IRB configurations can be set through multiple sources, each with its own precedence:

1. Command-Line Options: When some options are specified when starting IRB, they can override default settings.
2. Configuration File: If present, IRB reads a configuration file containing Ruby code to set configurations.
3. Environment Variables: Certain environment variables influence IRB's behavior.
4. Hash IRB.conf: This hash holds the current configuration settings, which can be modified during a session.

Configuration File Path Resolution

IRB searches for a configuration file in the following order:

1. $IRBRC
2. $XDG_CONFIG_HOME/irb/irbrc
3. $HOME/.irbrc
4. $HOME/.config/irb/irbrc
5. .irbrc in the current directory
6. irb.rc in the current directory
7. _irbrc in the current directory
8. $irbrc in the current directory

If the -f command-line option is used, no configuration file is loaded.

Method conf.rc? returns true if a configuration file was read, false otherwise. Hash entry IRB.conf[:RC] also contains that value.

Environment Variables

• NO_COLOR: Disables IRB's colorization.
• IRB_USE_AUTOCOMPLETE: Setting to false disables autocompletion.
• IRB_COMPLETOR: Configures auto-completion behavior (regexp or type).
• IRB_COPY_COMMAND: Overrides the default program used to interface with the system clipboard.
• VISUAL / EDITOR: Specifies the editor for the edit command.
• IRBRC: Specifies the rc-file for configuration.
• XDG_CONFIG_HOME: Used to locate the rc-file if IRBRC is unset.
• RI_PAGER / PAGER: Specifies the pager for documentation.
• IRB_LANG, LC_MESSAGES, LC_ALL, LANG: Determines the locale.

Hash IRB.conf

The initial entries in hash IRB.conf are determined by:

• Default values.
• Command-line options, which may override defaults.
• Direct assignments in the configuration file.

You can see the hash by typing IRB.conf. Below are the primary entries:

• :AP_NAME: IRB name[file.IRB@Application+Name];.html"code ruby">{ "$": :show_source, "@": :whereami, }

• :CONTEXT_MODE: Sets the mode[file.IRB@Context+Mode], the type of binding to be used when evaluating statements;.html"IRB.html" title="IRB (module)">library directory[file.p>

  .html"IRB.html" title="IRB (module)">name[file.IRB@IRB+Name];.html"IRB.html" title="IRB (module)">IRB session; initial value: IRB::Context object.

  • :MEASURE: Whether to performance[file.IRB@Performance+Measurement];.html"code ruby">{ :TIME=>#<Proc:0x0000556e271c6598 /var/lib/gems/3.0.0/gems/irb-1.8.3/lib/irb/init.rb:106>, :STACKPROF=>#<Proc:0x0000556e271c6548 /var/lib/gems/3.0.0/gems/irb-1.8.3/lib/irb/init.rb:116> }

  • :PROMPT: Hash of prompts[file.IRB@Prompt+and+Return+Formats];.html"code ruby">{ :NULL=>{:PROMPT_I=>nil, :PROMPT_S=>nil, :PROMPT_C=>nil, :RETURN=>"%s\n"}, :DEFAULT=>{:PROMPT_I=>"%N(%m):%03n> ", :PROMPT_S=>"%N(%m):%03n%l ", :PROMPT_C=>"%N(%m):%03n* ", :RETURN=>"=> %s\n"}, :CLASSIC=>{:PROMPT_I=>"%N(%m):%03n:%i> ", :PROMPT_S=>"%N(%m):%03n:%i%l ", :PROMPT_C=>"%N(%m):%03n:%i* ", :RETURN=>"%s\n"}, :SIMPLE=>{:PROMPT_I=>">> ", :PROMPT_S=>"%l> ", :PROMPT_C=>"?> ", :RETURN=>"=> %s\n"}, :INF_RUBY=>{:PROMPT_I=>"%N(%m):%03n> ", :PROMPT_S=>nil, :PROMPT_C=>nil, :RETURN=>"%s\n", :AUTO_INDENT=>true}, :XMP=>{:PROMPT_I=>nil, :PROMPT_S=>nil, :PROMPT_C=>nil, :RETURN=>" ==>%s\n"} }

  • :PROMPT_MODE: Name of prompt[file.IRB@Prompt+and+Return+Formats];.html"IRB.html" title="IRB (module)">loader[file.code>;.html"IRB.html" title="IRB (module)">tracer[file.IRB@Tracer];.html"IRB.html" title="IRB (module)">IRB object; initial value: main.

  Notes on Initialization Precedence

  • Any conflict between an entry in hash IRB.conf and a command-line option is resolved in favor of the hash entry.
  • Hash IRB.conf affects the context only once, when the configuration file is interpreted; any subsequent changes to it do not affect the context and are therefore essentially meaningless.

  Load Modules

  You can specify the names of modules that are to be required at startup.

  Array conf.load_modules determines the modules (if any) that are to be required during session startup. The array is used only during session startup, so the initial value is the only one that counts.

  The default initial value is [] (load no modules):

  irb(main):001> conf.load_modules
  => []
  

  You can set the default initial value via:

  • Command-line option -r

    $ irb -r csv -r json
    irb(main):001> conf.load_modules
    => ["csv", "json"]
    

  • Hash entry IRB.conf[:LOAD_MODULES] = *array*:

    IRB.conf[:LOAD_MODULES] = %w[csv json]

  Note that the configuration file entry overrides the command-line options.

  RI Documentation Directories

  You can specify the paths to RI documentation directories that are to be loaded (in addition to the default directories) at startup; see details about RI by typing ri --help.

  Array conf.extra_doc_dirs determines the directories (if any) that are to be loaded during session startup. The array is used only during session startup, so the initial value is the only one that counts.

  The default initial value is [] (load no extra documentation):

  irb(main):001> conf.extra_doc_dirs
  => []
  

  You can set the default initial value via:

  • Command-line option --extra_doc_dir

    $ irb --extra-doc-dir your_doc_dir --extra-doc-dir my_doc_dir
    irb(main):001> conf.extra_doc_dirs
    => ["your_doc_dir", "my_doc_dir"]
    

  • Hash entry IRB.conf[:EXTRA_DOC_DIRS] = *array*:

    IRB.conf[:EXTRA_DOC_DIRS] = %w[your_doc_dir my_doc_dir]

  Note that the configuration file entry overrides the command-line options.

  IRB Name

  You can specify a name for IRB.

  The default initial value is 'irb':

  irb(main):001> conf.irb_name
  => "irb"
  

  You can set the default initial value via hash entry IRB.conf[:IRB_NAME] = *string*:

  IRB.conf[:IRB_NAME] = 'foo'

  Application Name

  You can specify an application name for the IRB session.

  The default initial value is 'irb':

  irb(main):001> conf.ap_name
  => "irb"
  

  You can set the default initial value via hash entry IRB.conf[:AP_NAME] = *string*:

  IRB.conf[:AP_NAME] = 'my_ap_name'

  Configuration Monitor

  You can monitor changes to the configuration by assigning a proc to IRB.conf[:IRB_RC] in the configuration file:

  IRB.conf[:IRB_RC] = proc {|conf| puts conf.class }
  

  Each time the configuration is changed, that proc is called with argument conf: