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

When entering the identifier argument to M-., you can use the usual minibuffer completion commands (see Completion), with the known identifier names being the 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) is like apropos for tags (see Apropos). It displays a list of identifiers in the selected tags table whose names match the specified regexp. This is just like M-., except that it does regexp matching of identifiers instead of matching symbol names as fixed strings. By default, the command pops up the *xref* buffer, like M-., but you can display additional output by customizing the variable tags-apropos-additional-actions; see its documentation for details.

If any of the above commands finds more than one matching definition, it by default pops up the *xref* buffer showing the matching candidates. ( C-M-. always pops up the *xref* buffer if it finds at least one match.) The candidates are normally shown in that buffer as the name of a file and the matching identifier(s) in that file. In that buffer, you can select any of the candidates for display, and you have several additional commands, described in Commands Available in the *xref* Buffer. However, if the value of the variable xref-auto-jump-to-first-definition is move, the first of these candidates is automatically selected in the *xref* buffer, and if it’s t or show, the first candidate is automatically shown in its own window; t also selects the window showing the first candidate. The default value is nil, which just shows the candidates in the *xref* buffer, but doesn’t select any of them.

To go back to places from where you’ve displayed 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 Evaluating Emacs Lisp Expressions) 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 Find Identifier References). 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 Creating Tags Tables.)