@findex vc-dir-mark
@findex vc-dir-mark-all-files
While in the VC Directory buffer, all the files that you mark with
-@kbd{m} (@code{vc-dir-mark}) or @kbd{M} (@code{vc-dir-mark}) are in
-the current VC fileset. If you mark a directory entry with @kbd{m},
-all the listed files in that directory tree are in the current VC
-fileset. The files and directories that belong to the current VC
-fileset are indicated with a @samp{*} character in the VC Directory
-buffer, next to their VC status. In this way, you can set up a
-multi-file VC fileset to be acted on by VC commands like @w{@kbd{C-x v
-v}} (@pxref{Basic VC Editing}), @w{@kbd{C-x v =}} (@pxref{Old
-Revisions}), and @w{@kbd{C-x v u}} (@pxref{VC Undo}).
+@kbd{m} (@code{vc-dir-mark}) or @kbd{M} (@code{vc-dir-mark-all-files})
+are in the current VC fileset. If you mark a directory entry with
+@kbd{m}, all the listed files in that directory tree are in the
+current VC fileset. The files and directories that belong to the
+current VC fileset are indicated with a @samp{*} character in the VC
+Directory buffer, next to their VC status. In this way, you can set
+up a multi-file VC fileset to be acted on by VC commands like
+@w{@kbd{C-x v v}} (@pxref{Basic VC Editing}), @w{@kbd{C-x v =}}
+(@pxref{Old Revisions}), and @w{@kbd{C-x v u}} (@pxref{VC Undo}).
The VC Directory buffer also defines some single-key shortcuts for
VC commands with the @kbd{C-x v} prefix: @kbd{=}, @kbd{+}, @kbd{l},
can even guess the name of the function or other object that was
changed.
+@c Not worth it.
+@c @vindex change-log-directory-files
+To find the change log file, Emacs searches up the directory tree from
+the file you are editing. By default, it stops if it finds a
+directory that seems to be the root of a version-control repository.
+To change this, customize @code{change-log-directory-files}.
+
@vindex add-log-keep-changes-together
When the variable @code{add-log-keep-changes-together} is
non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file
Of course, you should substitute the proper years and copyright holder.
@node Xref
-@section Find Identifier Definitions and References
+@section Find Identifier References
@cindex xref
- An @dfn{identifier} is a syntactic elements of the program: a
-function, a subroutine, a method, a class, a data type, a macro, etc.
-In a programming language, each identifier is a symbol in the
-language's syntax. Many program development tools provide
-capabilities to extract references to identifiers from source files,
-record them on specialized data bases, and then use those data bases
-to quickly find where each identifier was defined and referenced.
+ An @dfn{identifier} is a name of a syntactical subunit of the
+program: a function, a subroutine, a method, a class, a data type, a
+macro, etc. In a programming language, each identifier is a symbol in
+the language's syntax. Program development and maintenance requires
+capabilities to quickly find where each identifier was defined and
+referenced, to rename identifiers across the entire project, etc.
-Emacs provides a unified user interface to these tools, called
-@samp{xref}. The tools supported by @samp{xref} include:
+These capabilities are also useful for finding references in major
+modes other than those defined to support programming languages. For
+example, chapters, sections, appendices, etc.@: of a text or a @TeX{}
+document can be treated as subunits as well, and their names can be
+used as identifiers. In this chapter, we use the term ``identifiers''
+to collectively refer to the names of any kind of subunits, in program
+source and in other kinds of text alike.
+
+Emacs provides a unified interface to these capabilities, called
+@samp{xref}.
+
+@cindex xref backend
+To do its job, @code{xref} needs to make use of information and to
+employ methods specific to the major mode. What files to search for
+identifiers, how to find references to identifiers, how to complete on
+identifiers---all this and more is mode-specific knowledge.
+@code{xref} delegates the mode-specific parts of its job to a
+@dfn{backend} provided by the mode; it also includes defaults for some
+of its commands, for those modes that don't provide their own.
+
+A backend can implement its capabilities in a variety of ways. Here
+are a few examples:
@enumerate a
@item
symbols. For example, Emacs Lisp symbols can be identified by
searching the package load history, maintained by the Emacs Lisp
interpreter, and by consulting the built-in documentation strings; the
-Emacs Lisp mode uses these facilities to find definitions of symbols.
-
-@item
-Etags, the command for tagging identifier definitions which is part of
-the Emacs distribution. @xref{Create Tags Table}.
-
-@item
-@acronym{GNU} GLOBAL, the source code tagging system, which provides
-the @command{gtags} command and associated utilities. @xref{Command
-Line, gtags, , global, GNU GLOBAL source code tag system}.
-
-@item
-Cscope (@uref{http://cscope.sourceforge.net/}, a tool for browsing
-source code.
-
-@item
-@acronym{GNU} IDUtils, a package for generating databases of
-identifier references and querying those databases. @xref{Top,,,
-idutils, ID database utilities}.
+Emacs Lisp mode uses these facilities in its backend to allow finding
+definitions of symbols. (One disadvantage of this kind of backend is
+that it only knows about subunits that were loaded into the
+interpreter.)
@item
-Grep, the venerable program that searches files for lines matching
-patterns. @xref{Invoking,,, grep, GNU Grep Manual}.
+An external program can extract references by scanning the relevant
+files, and build a database of these references. A backend can then
+access this database whenever it needs to list or look up references.
+The Emacs distribution includes @command{etags}, a command for tagging
+identifier definitions in programs, which supports many programming
+languages and other major modes, such as HTML, by extracting
+references into @dfn{tags tables}. @xref{Create Tags Table}. Major
+modes for languages supported by @command{etags} can use tags tables
+as basis for their backend. (One disadvantage of this kind of backend
+is that tags tables need to be kept reasonably up to date, by
+rebuilding them from time to time.)
@end enumerate
-@noindent
-Additional tools could be supported as they become available, or as
-user extensions. Each such tool is used as a @dfn{backend} by
-commands described in this section. Each command detects which
-backends are available for the current major mode, and uses the most
-capable of the available backends, with Grep generally serving as the
-fall-back backend.
-
-@cindex tag
-The commands described here are useful for finding references in major
-modes other than those defined to support programming languages. For
-example, chapters, sections, appendices, etc. of a text or a @TeX{}
-document can be treated as identifiers as well. In this chapter, we
-collectively refer to a reference that specifies the name of the file
-where the corresponding subunit is defined, and the position of the
-subunit's definition in that file, as a @dfn{tag}. We refer to the
-backends used by @code{xref} as @dfn{tagging backends}.
-
@menu
* Find Identifiers:: Commands to find where an identifier is defined
or referenced, to list identifiers, etc.
@node Find Identifiers
@subsection Find Identifiers
- This subsection describes the commands that use the tagging backends
-in order to find definitions of identifiers, references to
-identifiers, and perform various queries about identifiers. With most
-backends, these definitions and references were recorded as tags in
-the database created and maintained by the backend.
+ This subsection describes the commands that find references to
+identifiers and perform various queries about identifiers. Each such
+reference could @emph{define} an identifier, e.g., provide the
+implementation of a program subunit or the text of a document section;
+or it could @emph{use} the identifier, e.g., call a function or a
+method, assign a value to a variable, mention a chapter in a
+cross-reference, etc.
@menu
-* Looking Up Identifiers:: Commands to find the definition of a specific tag.
+* Looking Up Identifiers:: Commands to find the definition of an identifier.
* Xref Commands:: Commands in the @file{*xref*} buffer.
* Identifier Search:: Searching and replacing identifiers.
* List Identifiers:: Listing identifiers and completing on them.
Find definition of identifier, and display it in a new frame
(@code{xref-find-definitions-other-frame}).
@item M-,
-Pop back to where you previously invoked @kbd{M-.} and friends
+Go back to where you previously invoked @kbd{M-.} and friends
(@code{xref-pop-marker-stack}).
@end table
@findex xref-find-definitions
@kbd{M-.}@: (@code{xref-find-definitions}) shows the definitions of
the identifier at point. With a prefix argument, or if there's no
-valid identifier at point, it prompts for the identifier. If the
+identifier at point, it prompts for the identifier. If the
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 command @kbd{C-M-.} (@code{xref-find-apropos}) finds the
definitions of one or more identifiers that match a specified regular
expression. It is just like @kbd{M-.} except that it does regexp
-matching of identifiers instead of symbol name matching.
+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 @file{*xref*} buffer showing the definition candidates.
@findex xref-show-location-at-point
Display the reference on the current line in the other window
(@code{xref-show-location-at-point}).
-@findex xref-query-replace
+@findex xref-query-replace-in-results
@item r @var{pattern} @key{RET} @var{replacement} @key{RET}
Perform interactive query-replace on references that match
-@var{pattern} (@code{xref-query-replace}), replacing the match with
-@var{replacement}. @xref{Identifier Search}.
+@var{pattern} (@code{xref-query-replace-in-results}), replacing
+the match with @var{replacement}. @xref{Identifier Search}.
@findex xref-quit
@item q
Quit the window showing the @file{*xref*} buffer (@code{xref-quit}).
@cindex search and replace in multiple files
@cindex multiple-file search and replace
- The commands in this section visit and search all the files listed
-in the @code{xref} backend's database, one by one. For these
-commands, the database serves only to specify a sequence of files to
-search. These commands scan all the databases starting with the first
-one (if any) that describes the current file, proceed from there to
-the end of the list, and then scan from the beginning of the list
-until they have covered all the databases in the list.
+ The commands in this section perform various search and replace
+operations either on identifiers themselves or on files that reference
+them.
@table @kbd
@item M-?
Find all the references for the identifier at point.
-@item M-x xref-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
+@item M-x xref-query-replace-in-results @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
Interactively replace @var{regexp} with @var{replacement} in the names
of all the identifiers shown in the @file{*xref*} buffer.
@item M-x tags-search @key{RET} @var{regexp} @key{RET}
@kindex M-?
@findex xref-find-references
@kbd{M-?} finds all the references for the identifier at point. If
-there's no valid identifier at point, or when invoked with a prefix
+there's no identifier at point, or when invoked with a prefix
argument, the command prompts for the identifier, with completion. It
then presents a @file{*xref*} buffer with all the references to the
identifier, showing the file name and the line where the identifier is
referenced. The XREF mode commands are available in this buffer, see
@ref{Xref Commands}.
-@findex xref-query-replace
- @kbd{M-x xref-query-replace} reads a regexp to match identifier
-names and a string to replace with, just like ordinary @kbd{M-x
+@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
query-replace-regexp}. It then performs the specified replacement in
the names of the matching identifiers in all the places in all the
files where these identifiers are referenced. This is useful when you
searches for matches in all the files in the selected tags table, one
file at a time. It displays the name of the file being searched so
you can follow its progress. As soon as it finds an occurrence,
-@code{tags-search} returns. This command works only with the etags
-backend, and requires tags tables to be available (@pxref{Tags
-Tables}).
+@code{tags-search} returns. This command requires tags tables to be
+available (@pxref{Tags Tables}).
@findex tags-loop-continue
- Having found one match, you probably want to find all the rest.
-Type @kbd{M-x tags-loop-continue}) to resume the @code{tags-search},
-finding one more match. This searches the rest of the current buffer,
-followed by the remaining files of the tags table.
+ Having found one match with @code{tags-search}, you probably want to
+find all the rest. Type @kbd{M-x tags-loop-continue} to resume the
+@code{tags-search}, finding one more match. This searches the rest of
+the current buffer, followed by the remaining files of the tags table.
@findex tags-query-replace
@kbd{M-x tags-query-replace} performs a single
ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
tags-search}, but repeatedly, processing matches according to your
input. @xref{Query Replace}, for more information on query replace.
-This command works only with the etags backend.
@vindex tags-case-fold-search
@cindex case-sensitivity and tags search
replace subsequently by typing @kbd{M-x tags-loop-continue}; this
command resumes the last tags search or replace command that you did.
For instance, to skip the rest of the current file, you can type
-@kbd{M-> M-x tags-loop-continue}.
+@w{@kbd{M-> M-x tags-loop-continue}}.
- The commands in this section carry out much broader searches than
-the @code{xref-find-definitions} family. The
+ Note that the commands described above carry out much broader
+searches than the @code{xref-find-definitions} family. The
@code{xref-find-definitions} commands search only for definitions of
identifiers that match your string or regexp. The commands
-@code{tags-search} and @code{tags-query-replace} find every occurrence
-of the regexp, as ordinary search commands and replace commands do in
-the current buffer.
+@code{xref-find-references}, @code{tags-search}, and
+@code{tags-query-replace} find every occurrence of the identifier or
+regexp, as ordinary search commands and replace commands do in the
+current buffer.
- As an alternative to @code{tags-search}, you can run @command{grep}
-as a subprocess and have Emacs show you the matching lines one by one.
-@xref{Grep Searching}.
+ As an alternative to @code{xref-find-references} and
+@code{tags-search}, you can run @command{grep} as a subprocess and
+have Emacs show you the matching lines one by one. @xref{Grep
+Searching}.
@node List Identifiers
@subsubsection Identifier Inquiries
@table @kbd
@item C-M-i
@itemx M-@key{TAB}
-Perform completion on the text around point, using the @code{xref}
-backend if one is available (@code{completion-at-point}).
-@item M-x list-tags @key{RET} @var{file} @key{RET}
-Display a list of the tags defined in the program file @var{file}.
+Perform completion on the text around point, possibly using the
+selected tags table if one is loaded (@code{completion-at-point}).
@item M-x xref-find-apropos @key{RET} @var{regexp} @key{RET}
Display a list of all known identifiers matching @var{regexp}.
+@item M-x list-tags @key{RET} @var{file} @key{RET}
+Display a list of the identifiers defined in the program file
+@var{file}.
+@item M-x next-file
+Visit files recorded in the selected tags table.
@end table
@cindex completion (symbol names)
In most programming language modes, you can type @kbd{C-M-i} or
@kbd{M-@key{TAB}} (@code{completion-at-point}) to complete the symbol
-at point. If there is an @code{xref} backend available, this command
-can use it to generate completion candidates more intelligently.
+at point. Some modes provide specialized completion for this command
+tailored to the mode; for those that don't, if there is a tags table
+loaded, this command can use it to generate completion candidates.
@xref{Symbol Completion}.
@findex list-tags
The first time it is called, it visits the first file covered by the
table. Each subsequent call visits the next covered file, unless a
prefix argument is supplied, in which case it returns to the first
-file. This command works only with the etags backend.
+file. This command requires a tags table to be selected.
@node Tags Tables
@subsection Tags Tables
@cindex tags and tag tables
- A @dfn{tags table} records the tags extracted by scanning the source
-code of a certain program or a certain document. Tags extracted from
-generated files reference the original files, rather than the
-generated files that were scanned during tag extraction. Examples of
-generated files include C files generated from Cweb source files, from
-a Yacc parser, or from Lex scanner definitions; @file{.i} preprocessed
-C files; and Fortran files produced by preprocessing @file{.fpp}
-source files.
+ A @dfn{tags table} records the tags@footnote{
+A @dfn{tag} is a synonym for identifier reference. Commands and
+features based on the @code{etags} package traditionally use ``tag''
+with this meaning, and this subsection follows that tradition.
+} extracted by scanning the source code of a certain program or a
+certain document. Tags extracted from generated files reference the
+original files, rather than the generated files that were scanned
+during tag extraction. Examples of generated files include C files
+generated from Cweb source files, from a Yacc parser, or from Lex
+scanner definitions; @file{.i} preprocessed C files; and Fortran files
+produced by preprocessing @file{.fpp} source files.
@cindex etags
To produce a tags table, you run the @command{etags} shell command
@item
In Fortran code, functions, subroutines and block data are tags.
+@item
+In Go code, packages, functions, and types are tags.
+
@item
In HTML input files, the tags are the @code{title} and the @code{h1},
@code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchors
@item
In Ruby code, @code{def} or @code{class} or @code{module} at the
-beginning of a line generate a tag.
+beginning of a line generate a tag. Constants also generate tags.
@end itemize
You can also generate tags based on regexp matching (@pxref{Etags