Emacs/emacs/Looking-Up-Identifiers

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.)