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
- Show usages in the Find tool window
- Usages classification
- Find usages on associations and scopes
- Find usages improvements in v2019.3: delegates, enums, and more
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).
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.
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.
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.
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 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.
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.
The 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.
You can switch from the Preview to Call Hierarchy tab to show the call hierarchy for this method.
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.
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.
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.
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.
- 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.
- 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.
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.
It’s now also possible to look for usages of a scope.
Find usages improvements in v2019.3
Finally, let’s take a look at the most important find usages improvements made in v2019.3:
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.
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.
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.
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!
Your RubyMine Team