Next: Xref Commands, Up: Find Identifiers
The most important thing that xref enables you to do is to find
the definition of a specific identifier.
xref-find-definitions).
xref-find-apropos).
xref-find-definitions-other-window).
xref-find-definitions-other-frame).
xref-pop-marker-stack).
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 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). 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.)