28.4.1 Find Identifiers
This subsection describes the commands that find references to identifiers and perform various queries about identifiers. Each such reference could define an identifier, e.g., provide the implementation of a program subunit or the text of a document section; or it could use the identifier, e.g., call a function or a method, assign a value to a variable, mention a chapter in a cross-reference, etc.
| • Looking Up Identifiers |   | Commands to find the definition of an identifier. |
| • Xref Commands |   | Commands in the *xref* buffer. |
| • Identifier Search |   | Searching and replacing identifiers. |
| • List Identifiers |   | Listing identifiers and completing on them. |
28.4.1.1 Looking Up Identifiers​
The most important thing that xref enables you to do is to find the definition of a specific identifier.
M-.​
Find definitions of an identifier (xref-find-definitions).
C-M-. pattern RET​
Find all identifiers whose name matches pattern (xref-find-apropos).
C-x 4 . RET​
Find definitions of identifier, but display it in another window (xref-find-definitions-other-window).
C-x 5 . RET​
Find definition of identifier, and display it in a new frame (xref-find-definitions-other-frame).
M-x xref-find-definitions-at-mouse​
Find definition of identifier at mouse click.
M-,​
Go back to where you previously invoked M-. and friends (xref-pop-marker-stack).
M-x xref-etags-mode​
Switch xref to use the etags backend.
M-. (xref-find-definitions) shows the definitions of the identifier at point. With a prefix argument, or if there’s no identifier at point, it prompts for the identifier. (If you want it to always prompt, customize xref-prompt-for-identifier to t.)
If the specified identifier has only one definition, the command jumps to it. If the identifier has more than one possible definition (e.g., in an object-oriented language, or if there’s a function and a variable by the same name), the command shows the candidate definitions in the *xref* buffer, together with the files in which these definitions are found. Selecting one of these candidates by typing RET or clicking mouse-2 will pop a buffer showing the corresponding definition.
When entering the identifier argument to M-., the usual minibuffer completion commands can be used (see Completion), with the known identifier names as completion candidates.
Like most commands that can switch buffers, xref-find-definitions has a variant that displays the new buffer in another window, and one that makes a new frame for it. The former is C-x 4 . (xref-find-definitions-other-window), and the latter is C-x 5 . (xref-find-definitions-other-frame).
The command xref-find-definitions-at-mouse works like xref-find-definitions, but it looks for the identifier name at or around the place of a mouse event. This command is intended to be bound to a mouse event, such as C-M-mouse-1, for example.
The command C-M-. (xref-find-apropos) finds the definitions of one or more identifiers that match a specified regular expression. It is just like M-. except that it does regexp matching of identifiers instead of matching symbol names as fixed strings.
When any of the above commands finds more than one definition, it presents the *xref* buffer showing the definition candidates. In that buffer, you have several specialized commands, described in Xref Commands.
To go back to places from where you found the definition, use M-, (xref-pop-marker-stack). It jumps back to the point of the last invocation of M-.. Thus you can find and examine the definition of something with M-. and then return to where you were with M-,. M-, allows you to retrace your steps to a depth determined by the variable xref-marker-ring-length, which defaults to 16.
Some major modes install xref support facilities that might sometimes fail to find certain identifiers. For example, in Emacs Lisp mode (see Lisp Eval) M-. will by default find only functions and variables from Lisp packages which are loaded into the current Emacs session or are auto-loaded (see Autoload in The Emacs Lisp Reference Manual). If M-. fails to find some identifiers, you can try forcing xref to use the etags backend (see Xref). To this end, turn on the Xref Etags minor mode with M-x xref-etags-mode, then invoke M-. again. (For this to work, be sure to run etags to create the tags table in the directory tree of the source files, see Create Tags Table.)
28.4.1.2 Commands Available in the *xref* Buffer​
The following commands are provided in the *xref* buffer by the special XREF mode:
RET​
mouse-2​
Display the reference on the current line.
n​
.
Move to the next reference and display it in the other window (xref-next-line).
p​
,​
Move to the previous reference and display it in the other window (xref-prev-line).
C-o​
Display the reference on the current line in the other window (xref-show-location-at-point).
TAB​
Display the reference on the current line and bury the *xref* buffer (xref-quit-and-goto-xref).
r pattern RET replacement RET​
Perform interactive query-replace on references that match pattern (xref-query-replace-in-results), replacing the match with replacement. See Identifier Search.
g​
Refresh the contents of the *xref* buffer (xref-revert-buffer.
q​
Quit the window showing the *xref* buffer (xref-quit).
In addition, the usual navigation commands, such as the arrow keys, C-n, and C-p are available for moving around the buffer without displaying the references.
28.4.1.3 Searching and Replacing with Identifiers​
The commands in this section perform various search and replace operations either on identifiers themselves or on files that reference them.
M-?​
Find all the references for the identifier at point.
M-x xref-query-replace-in-results RET regexp RET replacement RET​
Interactively replace regexp with replacement in the names of all the identifiers shown in the *xref* buffer.
M-x tags-search RET regexp RET​
Search for regexp through the files in the selected tags table.
M-x tags-query-replace RET regexp RET replacement RET​
Perform a query-replace-regexp on each file in the selected tags table.
M-x fileloop-continue​
Restart one of the last 2 commands above, from the current location of point.
M-? finds all the references for the identifier at point, prompting for the identifier as needed, with completion. Depending on the current backend (see Xref), the command may prompt even if it finds a valid identifier at point. When invoked with a prefix argument, it always prompts for the identifier. (If you want it to prompt always, customize the value of the variable xref-prompt-for-identifier to t; or set it to nil to prompt only if there’s no usable identifier at point.) The command then presents the *xref* buffer with all the references to the identifier, showing the file name and the line where the identifier is referenced. The XREF mode commands are available in this buffer, see Xref Commands.
M-x xref-query-replace-in-results reads a regexp to match identifier names and a replacement string, just like ordinary M-x query-replace-regexp. It then performs the specified replacement in the names of the matching identifiers in all the places in all the files where these identifiers are referenced. This is useful when you rename your identifiers as part of refactoring. This command should be invoked in the *xref* buffer generated by M-?.
M-x tags-search reads a regexp using the minibuffer, then searches for matches in all the files in the selected tags table, one file at a time. It displays the name of the file being searched so you can follow its progress. As soon as it finds an occurrence, tags-search returns. This command requires tags tables to be available (see Tags Tables).
Having found one match with tags-search, you probably want to find all the rest. M-x fileloop-continue resumes the tags-search, finding one more match. This searches the rest of the current buffer, followed by the remaining files of the tags table.
M-x tags-query-replace performs a single query-replace-regexp through all the files in the tags table. It reads a regexp to search for and a string to replace with, just like ordinary M-x query-replace-regexp. It searches much like M-x tags-search, but repeatedly, processing matches according to your input. See Query Replace, for more information on query replace.
You can control the case-sensitivity of tags search commands by customizing the value of the variable tags-case-fold-search. The default is to use the same setting as the value of case-fold-search (see Lax Search).
It is possible to get through all the files in the tags table with a single invocation of M-x tags-query-replace. But often it is useful to exit temporarily, which you can do with any input event that has no special query replace meaning. You can resume the query replace subsequently by typing M-x fileloop-continue; this command resumes the last tags search or replace command that you did. For instance, to skip the rest of the current file, you can type M-> M-x fileloop-continue.
Note that the commands described above carry out much broader searches than the xref-find-definitions family. The xref-find-definitions commands search only for definitions of identifiers that match your string or regexp. The commands xref-find-references, tags-search, and tags-query-replace find every occurrence of the identifier or regexp, as ordinary search commands and replace commands do in the current buffer.
As an alternative to xref-find-references and tags-search, you can run grep as a subprocess and have Emacs show you the matching lines one by one. See Grep Searching.
28.4.1.4 Identifier Inquiries​
C-M-i​
M-TAB​
Perform completion on the text around point, possibly using the selected tags table if one is loaded (completion-at-point).
M-x xref-find-apropos RET regexp RET​
Display a list of all known identifiers matching regexp.
M-x list-tags RET file RET​
Display a list of the identifiers defined in the program file file.
M-x tags-next-file​
Visit files recorded in the selected tags table.
In most programming language modes, you can type C-M-i or M-TAB (completion-at-point) to complete the symbol at point. Some modes provide specialized completion for this command tailored to the mode; for those that don’t, if there is a tags table loaded, this command can use it to generate completion candidates. See Symbol Completion.
M-x list-tags reads the name of one of the files covered by the selected tags table, and displays a list of tags defined in that file. Do not include a directory as part of the file name unless the file name recorded in the tags table includes a directory. This command works only with the etags backend, and requires a tags table for the project to be available. See Tags Tables. If used interactively, the default tag is file name of the current buffer if used interactively.
M-x tags-next-file visits files covered by the selected tags table. The first time it is called, it visits the first file covered by the table. Each subsequent call visits the next covered file, unless a prefix argument is supplied, in which case it returns to the first file. This command requires a tags table to be selected.