argument, this command additionally prompts for the base directory
from which to start the search; this allows, for example, to limit the
search only to project files under a certain subdirectory of the
-project root.
+project root. The way this command displays the matches is affected
+by the value of @code{xref-auto-jump-to-first-xref} (@pxref{Identifier
+Search}).
@findex project-search
- @kbd{M-x project-search} is an interactive variant of
+ @kbd{M-x project-search} is an incremental variant of
@code{project-find-regexp}. It prompts for a regular expression to
search in the current project's files, but instead of finding all the
matches and displaying them, it stops when it finds a match and visits
by typing @kbd{@key{RET}} or clicking @kbd{mouse-2} will pop a buffer
showing the corresponding definition. If the value of the variable
@code{xref-auto-jump-to-first-definition} is @code{move}, the first
-candidate is automatically selected, and if it's @code{t} or
-@code{show}, the first candidate is automatically shown. The default
-value is @code{nil}, which just shows the candidates in the
-@file{*xref*} buffer, but doesn't select any of them.
-
-@vindex xref-auto-jump-to-first-xref
- If the value of the variable @code{xref-auto-jump-to-first-xref} is
-@code{t}, @emph{all} Xref commands automatically jump to the first
-result. If the value is @code{show}, the first result is shown, but
-the window showing the @file{*xref*} buffer is left selected. If the
-value is @code{move}, the first result is selected in the
-@file{*xref*} buffer, but is not shown. The default value is
-@code{nil}, which just shows the results in the @file{*xref*} buffer,
-but doesn't select any of them.
+of these candidates is automatically selected, and if it's @code{t} or
+@code{show}, the first candidate is automatically shown; @code{t} also
+selects the window showing the first candidate. The default value is
+@code{nil}, which just shows the candidates in the @file{*xref*}
+buffer, but doesn't select any of them.
When entering the identifier argument to @kbd{M-.}, the usual
minibuffer completion commands can be used (@pxref{Completion}), with
referenced. The XREF mode commands are available in this buffer, see
@ref{Xref Commands}.
+@vindex xref-auto-jump-to-first-xref
+ If the value of the variable @code{xref-auto-jump-to-first-xref} is
+@code{t}, @code{xref-find-references} automatically jumps to the first
+result and selects the window where it is displayed. If the value is
+@code{show}, the first result is shown, but the window showing the
+@file{*xref*} buffer is left selected. If the value is @code{move},
+the first result is selected in the @file{*xref*} buffer, but is not
+shown. The default value is @code{nil}, which just shows the results
+in the @file{*xref*} buffer, but doesn't select any of them.
+
@findex xref-query-replace-in-results
@kbd{M-x xref-query-replace-in-results} reads a regexp to match identifier
names and a replacement string, just like ordinary @kbd{M-x
@item M-x xref-find-apropos @key{RET} @var{regexp} @key{RET}
Display a list of all known identifiers matching @var{regexp}.
+The way this command displays the matches is affected by the value of
+@code{xref-auto-jump-to-first-xref} (@pxref{Identifier Search}).
@item M-x list-tags @key{RET} @var{file} @key{RET}
Display a list of the identifiers defined in the program file
interactively, the default tag is file name of the current buffer if
used interactively.
-@c Sadly, the new-and-improved Xref feature doesn't provide anything
-@c close to the described below features of the now-obsoleted
-@c tags-apropos. I'm leaving this here to encourage enhancements to
-@c xref.el.
+@c Sadly, the new-and-improved Xref feature doesn't provide some
+@c of the features of the now-obsoleted tags-apropos. I'm leaving
+@c this here to encourage enhancements to xref.el.
@ignore
@findex tags-apropos
@vindex tags-apropos-verbose
+++
*** New user options to automatically show the first Xref match.
The new user option 'xref-auto-jump-to-first-definition' controls the
-behavior of 'xref-find-definitions' and related commands: if it's t or
-'show', the first match is automatically displayed; if it's 'move',
-point in the "*xref*" buffer is automatically moved to the first match
-without displaying it.
-The new user option 'xref-auto-jump-to-first-xref' changes the behavior of
-all Xref commands in the same way as 'xref-auto-jump-to-first-definition'
-affects the "find-definitions" commands.
+behavior of 'xref-find-definitions' and related commands, like
+'xref-find-definitions-other-windo': if it's t or 'show', the first
+match is automatically displayed; if it's 'move', point in the
+"*xref*" buffer is automatically moved to the first match without
+displaying it.
+The new user option 'xref-auto-jump-to-first-xref' changes the
+behavior of Xref commands such as 'xref-find-references',
+'xref-find-apropos', and 'project-find-regexp', which are expected to
+display many match that the user would like to
+visit. 'xref-auto-jump-to-first-xref' changes their behavior muuch in
+the same way as 'xref-auto-jump-to-first-definition' affects the
+"find-definitions" commands.
*** New user options 'xref-search-program' and 'xref-search-program-alist'.
So far 'grep' and 'ripgrep' are supported. 'ripgrep' seems to offer better
"If t, `xref-find-definitions' always jumps to the first result.
`show' means to show the first result's location, but keep the
focus on the Xref buffer's window.
-`move' means to only move point to the first result."
+`move' means to only move point to the first result.
+This variable also affects commands similar to `xref-find-definitions',
+such as `xref-find-definitions-other-window'."
:type '(choice (const :tag "Jump" t)
(const :tag "Show" show)
(const :tag "Move point only" move)
:package-version '(xref . "1.2.0"))
(defcustom xref-auto-jump-to-first-xref nil
- "If t, xref commands always jump to the first result.
+ "If t, `xref-find-references' always jumps to the first result.
`show' means to show the first result's location, but keep the
focus on the Xref buffer's window.
`move' means to only move point to the first result.
+This variable also affects commands similar to `xref-find-definitions',
+such as `xref-find-references-at-mouse', `xref-find-apropos',
+and `project-find-regexp'.
-Please be careful changing this value if you are using Emacs 27
-or earlier: it can break dired-do-find-regexp-and-replace."
+Please be careful when changing the value if you are using Emacs 27
+or earlier: it can break `dired-do-find-regexp-and-replace'."
:type '(choice (const :tag "Jump" t)
(const :tag "Show" show)
(const :tag "Move point only" move)
projects / emacs.git / commitdiff