Next: Xref Commands, 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-pop-marker-stack
).
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 Xref Commands. 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 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 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.)
Next: Xref Commands, Up: Find Identifiers [Contents][Index]