Next: Commands Available in the *xref* Buffer, Up: Find Identifiers [Contents][Index]
The most important thing that xref enables you to do is to find
the definition of a specific identifier.
Find definitions of an identifier (xref-find-definitions).
Find all identifiers whose name matches pattern
(xref-find-apropos).
Find definitions of identifier, but display it in another window
(xref-find-definitions-other-window).
Find definition of identifier, and display it in a new frame
(xref-find-definitions-other-frame).
Find definition of identifier at mouse click.
Go back to where you previously invoked M-. and friends
(xref-go-back).
Go forward to where you previously invoked M-,
(xref-go-forward).
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 and selects that buffer’s window. (C-M-.
always pops up the *xref* buffer if it finds at least
one match.) Each candidate is 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, Emacs
automatically moves point to the first of these candidates in the
*xref* buffer, so just typing RET will display the
definition of that candidate. If the value of the variable is
t or show, the first candidate is automatically shown in
its own window; t also selects the window showing the first
candidate’s definition, while show leaves the window of the
*xfer* buffer selected. The default value is nil, which
just shows the candidates in the *xref* buffer, but neither
selects any of them nor shows their definition, until you select a
candidate in the *xref* buffer.
If you switch away of the window showing the *xref* buffer
which displays several candidates, you can move from one candidate to
another using the commands M-g M-n (next-error) and
M-g M-p (previous-error). See Compilation Mode.
To go back to places from where you’ve displayed the
definition, use M-, (xref-go-back). 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 the
steps you made forward in the history of places, all the way to the
first place in history, where you first invoked M-., or to any
place in-between.
If you previously went back too far with M-,, or want to
re-examine a place from which you went back, you can use C-M-,
(xref-go-forward) to go forward again. This is similar to
using M-., except that you don’t need on each step to move point
to the identifier whose definition you want to look up. C-M-,
allows you to retrace all the steps you made back in the history of
places, all the way to the last place in history, where you invoked
M-,, or to any place in-between.
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.)
Next: Commands Available in the *xref* Buffer, Up: Find Identifiers [Contents][Index]