Find usages in RubyMine

Find usages can be used to find all the pieces of code referencing a specific element, such as a class, method, symbol, or many of the others. RubyMine can also find dynamic usages, including Rails associations, factories, or delegates. You have the ability to specify the scope and search through an open file, project, referenced libraries, and so on.
Find usages is very helpful for investigating a project and refactoring your code. For example, the Rename refactoring requires high accuracy when finding usages for a target element, so that you can trust the IDE when making such changes.
In this blog post, we’ll show you how to show usages of an element in the editor or separate window, change the search scope, change the layout of a report with search results, and so on.

Show usages in the editor

RubyMine allows you to find usages for various Ruby/Rails elements, including methods, symbols, classes, and so on. For example, to show the usages of a specific method in a popup, place the caret at the method name and select Edit | Find | Show Usages (⌃⌥F7 / Ctrl+Alt+F7).
Find usages in a popup
RubyMine also understands whether or not a target element is a declaration on its own (for example, class, method, or variable), and allows you to find usages using navigation. To do this, hover the mouse pointer over the method name while holding down the ⌘ / Ctrl key. RubyMine will show a popup corresponding to this method. The method will turn into a hyperlink, which is possible to click if the ⌘ / Ctrl key is still held.
Navigate to usages
As you can see, RubyMine can show not only method usages but symbols/hash keys with the same name in the invoked popup. These symbols/hash keys may be unrelated to the target method, so you can disable searching for them. Click the Settings button in the top right corner of the popup to get the Find Usages dialog and, if necessary, disable the Symbols/hash keys option.
Find Usages settings: disable symbol/hash
You can also invoke this dialog from the main menu Edit | Find | Find Usages Settings or by pressing ⌥⇧⌘F7 / Ctrl+Shift+Alt+F7. This dialog lets you change the scope for finding usages. There are multiple options, including only project files, projects and libraries, test files, and so on.
Find Usages settings: scopes
After you have selected the required scope, click Find. For example, with the Current File scope, RubyMine will show only usages from the file that is currently open (users_controller.rb in the image below).

You can review all usages in detail using the dedicated Find tool window that can be opened with the Open in Find Tool Window button (⌥F7 / Alt+F7). In the next chapter, we’ll look at how to invoke this window and then examine the results.

Show usages in the Find tool window

In the previous chapter, we learned how to show usages in a popup in the editor. If you are looking for usages of an element widely used across your project, it might be necessary to carefully examine the results in a separate window. For example, to search for usages of a method, place the caret at the method name and use Edit | Find | Find Usages (⌥F7 / Alt+F7) from the main menu. RubyMine will start searching for usages and display them in a separate Find tool window.
Find Usages tool window
In the example above, usages are grouped by usage type and file structure. You can change the layout of this report and group usages by directory, module, and so on. To do this, click the Group By button on the toolbar on the left and choose the desired action.
Find Usages tool window: groups
The Preview Usages button on the left toolbar allows you to open the actual piece of code for the selected usage. For instance, in the example below the Preview tab shows the change_settings method call right in the Find tool window.

Find Usages tool window: preview
You can switch from the Preview to Call Hierarchy tab to show the call hierarchy for this method.
Find Usages tool window: call hierarchy
For this call hierarchy, you can specify the desired Scope: for example, this can be the current class or the entire project.

One more useful capability of the Find tool window is its ability to filter usages of the selected variable or constant, by access type (read or write access). To do this, use the Show read access and Show write access buttons on the left toolbar.
Find Usages tool window: read/write access

Usages classification

Usages displayed in the Find tool window can be classified by their types. In the example below, usages of the change_password method are divided into two categories – Method call and Symbol/hash key.
Usage types
There are other usage types that depend on the target element and its references: Declaration, Partial declaration, Usage in comments, and so on. Let’s look at some examples that demonstrate the different usages types.

  • Declaration

    Typically this group displays usages of constants or parameters that don’t have default values. In the example below, the user_data method parameter is processed as a declaration.
    Declaration

  • Usage in string literals

    This group contains references that are inside string literals.
    For example, the “Relationship” value passed as a class_name falls into this group.
    String literal

  • Usage in comments

    This group contains usages of the target element in comments. In the example below, RubyMine finds the path method parameter in a YARD annotation and shows it in the Usage in comments group.
    Comment

You can learn more about improvements in usage classification from the following ticket: https://youtrack.jetbrains.com/issue/RUBY-23788. Feel free to leave feedback and suggest new useful usage types.

Find usages on associations and scopes

Another useful feature is Find usages on associations. In this case, RubyMine looks at all methods defined by the association. For example, in a singular association belongs_to :user, it will include user, user=, build_user, create_user, create_user!, and reload_user.
Associations
It’s now also possible to look for usages of a scope.
Scopes

Find usages improvements in v2019.3

Finally, let’s take a look at the most important find usages improvements made in v2019.3:

  • RUBY-22561

    RubyMine now correctly handles delegates with prefixes and finds their corresponding usages.

    We’ve also improved rename refactoring in such cases. For example, if you try to remove the user prefix when renaming the user_followers method call, RubyMine will warn you about the incorrect name.
    Rename delegate

  • RUBY-24396

    As you may know, RubyMine allows you to navigate to an element’s declaration by holding ⌘ / Ctrl and clicking on the element. Starting with v2019.3, RubyMine understands that an element is a declaration by itself (for example, class, method, or variable) and shows a corresponding tooltip when holding ⌘ / Ctrl and hovering over the element. When the element turns into a hyperlink, click it without releasing the ⌘ /Ctrl key to show its usages inline.
    Find usages in a popup
    Please note this feature is not implemented yet for variables and parameters as it requires reworking the resolve logic. Feel free to leave your feedback about this feature in RUBY-24396.

  • RUBY-24651

    In v2019.3, we’ve also fixed find usages for rails enums.

Try out the new features and let us know about any issues you come across in the comments section. Please also feel free to submit an issue or feature suggestion to YouTrack. Thank you!

Download RubyMine 2019.3 EAP

Cheers,
Your RubyMine Team

This entry was posted in Learn RubyMine, What's New (EAP) and tagged , , , . Bookmark the permalink.

3 Responses to Find usages in RubyMine

  1. Dave says:

    Awesome post. This is great info.

  2. Gleb says:

    Hello,
    Thank you for awesome set of products.
    Is IDEA Ruby plugin somehow aligned to features to RubyMine? Any changelog?

    • Andrey Aksenov says:

      Hi

      RubyMine and the Ruby plugin for IntelliJ IDEA have the same functionality. However, because of the differences in release cycles, the latest features and bug fixes become available in the Ruby plugin a little later than they do in RubyMine.
      To see a list of changes for RubyMine, please check out the What’s New page and Release Notes.

Leave a Reply

Your email address will not be published. Required fields are marked *