Using Rubyscope

Install

You need Linux or macOS, Rust 1.88 or newer, and clang with libclang. The Prism parser is compiled from C when you build.

Linux

git clone https://github.com/equivalent/rubyscope
cd rubyscope
bin/install

This builds the release binaries and installs rubyscope and rubyscope-cli in ~/.local/bin, an app launcher entry and the icon. Make sure ~/.local/bin is on your PATH.

macOS

bin/install-macos

This installs ~/Applications/rubyscope.app, which you can open from Spotlight or the Dock, and a link to it in ~/.local/bin. An app started from the Dock gets only the system PATH, so Rubyscope reads the PATH of your login shell when it starts.

Optional tools

Open a project

rubyscope ~/code/shop                             # open a project folder
rubyscope ~/code/shop/app/models/order.rb:40      # open a file at line 40
rubyscope                                         # the current folder, or the start screen

• With a file and no folder, the project is the nearest parent folder that has .git or a Gemfile.
• With no arguments, Rubyscope opens the current folder when it has .git or a Gemfile. Otherwise it shows the start screen, with a path field, a "Browse…" button and your recent projects.
• Ctrl O opens the system folder dialog. When a project is already open, the new one opens in a new window.
• Rubyscope remembers the open tabs of each project and opens them again next time.

First steps

1. Open a project. The index builds in the background, and the top bar shows "indexing…" and then the number of files. The first index of a large app takes a few seconds. The next start takes about one second.
2. Open a file. Press Ctrl P and type part of the path, or click it in the file tree. Press Ctrl T to find a class, module, method or constant by name.
3. Hold Ctrl. The names you can click get an underline. Click one to go to its definition. When there are several, Rubyscope shows a list. When a class is opened in many files, it goes to the main file and tells you how many there are.
4. Go back with the mouse back button or the back button in the top bar. The forward button goes forward again.
5. Right-click a name and choose "Find usages". The results panel opens at the bottom. For a method, the "callers" button on a row shows who calls the method around that row.
6. Rest the pointer on a name for half a second. A popup shows the signature, the docs, where it is defined, the type Rubyscope found and how sure it is.
7. Press Ctrl B to show git blame. Newer commits get a stronger blue. Click a blame line to open the commit, or its pull request, on GitHub.
8. Press Ctrl K to see every command.

The window

Mouse

Keys

Ctrl F and Ctrl Shift F start with the selected text when it is on one line.

Scroll keys

These keys scroll the code when no text field has focus.

The mouse wheel scrolls three times faster than usual in egui apps. Hold Shift to scroll a page at a time.

Commands without a key

These are in the Ctrl K list. They have no key, but you can give them one.

"Open in editor" uses omarchy-launch-editor when it is on PATH. Otherwise it opens nvim in a terminal. On macOS it opens nvim in a new Terminal window. "Open on GitHub" needs an origin remote on github.com and opens the line at the commit of HEAD.

Change the keys

Put your keys in ~/.config/rubyscope/keys.toml. A key in this file replaces the default key of that command. The other commands keep their defaults. Rubyscope reads the file when it starts.

toggle_blame = "cmd+alt+b"
find_usages = "alt+u"
back = "alt+left"
forward = "alt+right"
reindex = "f5"

A key is modifiers and one key, joined with +. The modifiers are cmd, ctrl, shift and alt. cmd is Cmd on macOS and Ctrl on Linux, so one file works on both. ctrl is always the Ctrl key. The key can be a letter, a digit, esc, tab, enter, space, an arrow (left, right, up, down) or f1 to f12.

What a click understands

• Constants. Ruby's constant lookup through lexical scopes, ancestors and the top level. Compact names (class A::B), constant aliases and Zeitwerk folder namespaces. A click on a namespace lists the classes in it.
• Methods. Ruby's lookup order: prepends, the class, includes, the superclass. Class methods, class << self, extend, module_function, concerns (class_methods do, included do), class_eval, ActiveSupport.on_load and super.
• Rails DSLs. Associations, scopes, enums, delegate, class_attribute and mattr_*, attr_*, attribute, store_accessor, attachments, alias_attribute, and columns from db/schema.rb.
• Symbols that name methods. before_action :load, validate :check, if: :paid?, send(:x).
• Variable types. Model.find, relations and scopes, associations, block parameters, instance variables, return values, YARD @return, FactoryBot create(:x), and as a last guess the variable's name. The hover shows how sure each answer is: exact, inferred, guess or name only.
• Phlex. Kit calls such as Button(...) and UI::Button(...) go to UI::Button, also from a module that a class with the kit includes.
• Controllers and views. OrdersController#edit and app/views/orders/edit.* both ways, variant folders, and Views::Orders::Edit. Mailer methods and their templates the same way.
• Routes. Route helpers such as admin_order_path go to the route line. In routes files, resources :x goes to the controller and to: "a#b" to the action.
• Translations. t("a.b") and lazy t(".x") in controllers, Phlex and templates go to the locale YAML line, for every locale.
• Partials. render "x/y" goes to the partial. In ERB templates, the Ruby inside the tags works like any Ruby.
• Tests. RSpec let and subject, described_class, shared examples, methods in describe blocks, FactoryBot factories and traits.
• Stimulus. data-controller and data-action, in ERB and in Phlex hashes, go to the controller file and method.
• Gems. Gems from Gemfile.lock and the Ruby standard library.

The saved index

Rubyscope lists the project files and respects .gitignore. It reads Gemfile.lock and asks the project's Ruby where the gems and the standard library are. It parses every Ruby file with Prism on all CPU cores, joins the files into one table, and adds the Rails, RSpec, FactoryBot and Stimulus rules.

The result is saved in ~/.cache/rubyscope/, or in $XDG_CACHE_HOME/rubyscope/. At the next start Rubyscope parses only the files whose size or change time is different. For a large Rails app with its gems, the index is ready in less than a second with the saved index, and in a few seconds without it.

While the window is open, a file watcher sees changes in app/, config/, db/, lib/, spec/, test/, Gemfile and Gemfile.lock. Open tabs load the new text and the index builds again from the changed files.

The saved index is not used after a new build of Rubyscope with new parse rules, or when config/initializers/inflections.rb changed. "Index the project again" in Ctrl K parses every file and writes a new saved index.

Limits

• Methods with names that exist only at runtime, such as define_method with a variable name, method_missing or class_eval with a string, cannot be found by reading the code. For these, Rubyscope lists the methods with that name.
• Some variable types are guesses. The hover always says when a type is a guess.
• RBS signatures for core classes are not read yet. "x".strip gives a name-only list, because String is written in C.
• Custom Zeitwerk setups are read from the initializers only.
• Files outside the watched folders do not update the index while the window is open. Use "Index the project again".

Files Rubyscope writes

Rubyscope never writes into the project folder.

It reads ~/.config/rubyscope/keys.toml for keys and the current Omarchy theme for colors.

Environment variables

Troubleshooting

Command-line tool

rubyscope-cli builds the same index as the window and answers questions about it. Use it to test the index or to script a lookup. Positions are FILE:LINE:COL, starting at 1.

rubyscope-cli -r ~/code/shop index                         # build the index, print counts and times
rubyscope-cli -r ~/code/shop def app/models/order.rb:12:5  # where the name goes
rubyscope-cli -r ~/code/shop refs app/models/order.rb:12:5 # every usage, the first 40
rubyscope-cli -r ~/code/shop hover app/models/order.rb:12:5
rubyscope-cli -r ~/code/shop related app/controllers/orders_controller.rb:8:7
rubyscope-cli -r ~/code/shop outline app/models/order.rb
rubyscope-cli -r ~/code/shop search "ready_to_ship"
rubyscope-cli -r ~/code/shop search --regex "def (create|update)"
rubyscope-cli -r ~/code/shop ancestors ApplicationRecord

To compare Rubyscope with a booted Rails app, run probe/rails_probe.rb inside the app with bin/rails runner, then rubyscope-cli check on the JSON file it writes. See the README for details.