Emacs/docs/latest/emacs/Looking-Up-Identifiers
Next: Xref Commands, Up: Find Identifiers [Contents][Index]
28.4.1.1 Looking Up Identifiers
The most important thing that xref
enables you to do is to find the definition of a specific identifier.
- M-.
- Find definitions of an identifier (
xref-find-definitions
). - C-M-.
pattern
RET - Find all identifiers whose name matches
pattern
(xref-find-apropos
). - C-x 4 . RET
- Find definitions of identifier, but display it in another window (
xref-find-definitions-other-window
). - C-x 5 . RET
- Find definition of identifier, and display it in a new frame (
xref-find-definitions-other-frame
). - M-x xref-find-definitions-at-mouse
- Find definition of identifier at mouse click.
- M-,
- Go back to where you previously invoked M-. and friends (
xref-pop-marker-stack
). - M-x xref-etags-mode
- Switch
xref
to use theetags
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 . /@w (xref-find-definitions-other-window
), and the latter is C-x 5 . /@w (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
) 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 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 /@w , 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]