The most important thing that
xref enables you to do is to find
the definition of a specific identifier.
xrefto use the
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
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 . (
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
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). 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.)