The most important thing that
xref enables you to do is to find
the definition of a specific identifier.
Find definitions of an identifier (
Find all identifiers whose name matches pattern
Find definitions of identifier, but display it in another window
Find definition of identifier, and display it in a new frame
Find definition of identifier at mouse click.
Go back to where you previously invoked M-. and friends
xref to use the
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
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-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
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 Xref Commands. However, if the value of
the first of these candidates is automatically selected in the
*xref* buffer, and if it’s
show, the first
candidate is automatically shown in its own window;
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 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
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.)