1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
3 @c 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Maintaining, Abbrevs, Building, Top
6 @chapter Maintaining Large Programs
8 This chapter describes Emacs features for maintaining large
9 programs. The version control features (@pxref{Version Control}) are
10 also particularly useful for this purpose.
13 * Change Log:: Maintaining a change history for your program.
14 * Format of ChangeLog:: What the change log file looks like.
15 * Tags:: Go direct to any function in your program in one
16 command. Tags remembers which file it is in.
22 A change log file contains a chronological record of when and why you
23 have changed a program, consisting of a sequence of entries describing
24 individual changes. Normally it is kept in a file called
25 @file{ChangeLog} in the same directory as the file you are editing, or
26 one of its parent directories. A single @file{ChangeLog} file can
27 record changes for all the files in its directory and all its
32 @findex add-change-log-entry-other-window
33 The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
34 file for the file you are editing
35 (@code{add-change-log-entry-other-window}). If that file is actually
36 a backup file, it makes an entry appropriate for the file's
37 parent---that is useful for making log entries for functions that
38 have been deleted in the current version.
40 @kbd{C-x 4 a} visits the change log file and creates a new entry
41 unless the most recent entry is for today's date and your name. It
42 also creates a new item for the current file. For many languages, it
43 can even guess the name of the function or other object that was
46 @vindex add-log-keep-changes-together
47 When the variable @code{add-log-keep-changes-together} is
48 non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file
49 rather than starting a new item.
51 @vindex add-log-always-start-new-record
52 If @code{add-log-always-start-new-record} is non-@code{nil},
53 @kbd{C-x 4 a} always makes a new entry, even if the last entry
54 was made by you and on the same date.
56 @vindex change-log-version-info-enabled
57 @vindex change-log-version-number-regexp-list
58 @cindex file version in change log entries
59 If the value of the variable @code{change-log-version-info-enabled}
60 is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the
61 change log entry. It finds the version number by searching the first
62 ten percent of the file, using regular expressions from the variable
63 @code{change-log-version-number-regexp-list}.
65 @cindex Change Log mode
66 @findex change-log-mode
67 The change log file is visited in Change Log mode. In this major
68 mode, each bunch of grouped items counts as one paragraph, and each
69 entry is considered a page. This facilitates editing the entries.
70 @kbd{C-j} and auto-fill indent each new line like the previous line;
71 this is convenient for entering the contents of an entry.
73 @findex change-log-merge
74 You can use the command @kbd{M-x change-log-merge} to merge other
75 log files into a buffer in Change Log Mode, preserving the date
78 Version control systems are another way to keep track of changes in your
79 program and keep a change log. @xref{Log Buffer}.
81 @node Format of ChangeLog
82 @section Format of ChangeLog
84 A change log entry starts with a header line that contains the current
85 date, your name, and your email address (taken from the variable
86 @code{add-log-mailing-address}). Aside from these header lines, every
87 line in the change log starts with a space or a tab. The bulk of the
88 entry consists of @dfn{items}, each of which starts with a line starting
89 with whitespace and a star. Here are two entries, both dated in May
90 1993, with two items and one item respectively.
96 1993-05-25 Richard Stallman <rms@@gnu.org>
98 * man.el: Rename symbols `man-*' to `Man-*'.
99 (manual-entry): Make prompt string clearer.
101 * simple.el (blink-matching-paren-distance):
102 Change default to 12,000.
104 1993-05-24 Richard Stallman <rms@@gnu.org>
106 * vc.el (minor-mode-map-alist): Don't use it if it's void.
107 (vc-cancel-version): Doc fix.
110 One entry can describe several changes; each change should have its
111 own item, or its own line in an item. Normally there should be a
112 blank line between items. When items are related (parts of the same
113 change, in different places), group them by leaving no blank line
116 You should put a copyright notice and permission notice at the
117 end of the change log file. Here is an example:
120 Copyright 1997, 1998 Free Software Foundation, Inc.
121 Copying and distribution of this file, with or without modification, are
122 permitted provided the copyright notice and this notice are preserved.
126 Of course, you should substitute the proper years and copyright holder.
132 A @dfn{tags table} is a description of how a multi-file program is
133 broken up into files. It lists the names of the component files and the
134 names and positions of the functions (or other named subunits) in each
135 file. Grouping the related files makes it possible to search or replace
136 through all the files with one command. Recording the function names
137 and positions makes possible the @kbd{M-.} command which finds the
138 definition of a function by looking up which of the files it is in.
140 Tags tables are stored in files called @dfn{tags table files}. The
141 conventional name for a tags table file is @file{TAGS}.
143 Each entry in the tags table records the name of one tag, the name of the
144 file that the tag is defined in (implicitly), and the position in that
145 file of the tag's definition. When a file parsed by @code{etags} is
146 generated from a different source file, like a C file generated from a
147 Cweb source file, the tags of the parsed file reference the source
150 Just what names from the described files are recorded in the tags table
151 depends on the programming language of the described file. They
152 normally include all file names, functions and subroutines, and may
153 also include global variables, data types, and anything else
154 convenient. Each name recorded is called a @dfn{tag}.
156 @cindex C++ class browser, tags
158 @cindex class browser, C++
160 See also the Ebrowse facility, which is tailored for C++.
161 @xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}.
164 * Tag Syntax:: Tag syntax for various types of code and text files.
165 * Create Tags Table:: Creating a tags table with @code{etags}.
166 * Etags Regexps:: Create arbitrary tags using regular expressions.
167 * Select Tags Table:: How to visit a tags table.
168 * Find Tag:: Commands to find the definition of a specific tag.
169 * Tags Search:: Using a tags table for searching and replacing.
170 * List Tags:: Listing and finding tags defined in a file.
174 @subsection Source File Tag Syntax
176 Here is how tag syntax is defined for the most popular languages:
180 In C code, any C function or typedef is a tag, and so are definitions of
181 @code{struct}, @code{union} and @code{enum}.
182 @code{#define} macro definitions and @code{enum} constants are also
183 tags, unless you specify @samp{--no-defines} when making the tags table.
184 Similarly, global variables are tags, unless you specify
185 @samp{--no-globals}. Use of @samp{--no-globals} and @samp{--no-defines}
186 can make the tags table file much smaller.
188 You can tag function declarations and external variables in addition
189 to function definitions by giving the @samp{--declarations} option to
190 @code{etags}. You can tag struct members with the @samp{--members}
194 In C++ code, in addition to all the tag constructs of C code, member
195 functions are also recognized, and optionally member variables if you
196 use the @samp{--members} option. Tags for variables and functions in
197 classes are named @samp{@var{class}::@var{variable}} and
198 @samp{@var{class}::@var{function}}. @code{operator} definitions have
199 tag names like @samp{operator+}.
202 In Java code, tags include all the constructs recognized in C++, plus
203 the @code{interface}, @code{extends} and @code{implements} constructs.
204 Tags for variables and functions in classes are named
205 @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
208 In La@TeX{} text, the argument of any of the commands @code{\chapter},
209 @code{\section}, @code{\subsection}, @code{\subsubsection},
210 @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite},
211 @code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry},
212 @code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand},
213 @code{\newenvironment} or @code{\renewenvironment} is a tag.@refill
215 Other commands can make tags as well, if you specify them in the
216 environment variable @env{TEXTAGS} before invoking @code{etags}. The
217 value of this environment variable should be a colon-separated list of
218 command names. For example,
221 TEXTAGS="mycommand:myothercommand"
226 specifies (using Bourne shell syntax) that the commands
227 @samp{\mycommand} and @samp{\myothercommand} also define tags.
230 In Lisp code, any function defined with @code{defun}, any variable
231 defined with @code{defvar} or @code{defconst}, and in general the first
232 argument of any expression that starts with @samp{(def} in column zero is
236 In Scheme code, tags include anything defined with @code{def} or with a
237 construct whose name starts with @samp{def}. They also include variables
238 set with @code{set!} at top level in the file.
241 Several other languages are also supported:
246 In Ada code, functions, procedures, packages, tasks and types are
247 tags. Use the @samp{--packages-only} option to create tags for
250 In Ada, the same name can be used for different kinds of entity
251 (e.g.@:, for a procedure and for a function). Also, for things like
252 packages, procedures and functions, there is the spec (i.e.@: the
253 interface) and the body (i.e.@: the implementation). To make it
254 easier to pick the definition you want, Ada tag name have suffixes
255 indicating the type of entity:
272 Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
273 directly to the body of the package @code{bidule}, while @kbd{M-x
274 find-tag @key{RET} bidule @key{RET}} will just search for any tag
278 In assembler code, labels appearing at the beginning of a line,
279 followed by a colon, are tags.
282 In Bison or Yacc input files, each rule defines as a tag the nonterminal
283 it constructs. The portions of the file that contain C code are parsed
287 In Cobol code, tags are paragraph names; that is, any word starting in
288 column 8 and followed by a period.
291 In Erlang code, the tags are the functions, records and macros defined
295 In Fortran code, functions, subroutines and block data are tags.
298 In HTML input files, the tags are the @code{title} and the @code{h1},
299 @code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchors
300 and all occurrences of @code{id=}.
303 In Lua input files, all functions are tags.
306 In makefiles, targets are tags; additionally, variables are tags
307 unless you specify @samp{--no-globals}.
310 In Objective C code, tags include Objective C definitions for classes,
311 class categories, methods and protocols. Tags for variables and
312 functions in classes are named @samp{@var{class}::@var{variable}} and
313 @samp{@var{class}::@var{function}}.
316 In Pascal code, the tags are the functions and procedures defined in
320 In Perl code, the tags are the packages, subroutines and variables
321 defined by the @code{package}, @code{sub}, @code{my} and @code{local}
322 keywords. Use @samp{--globals} if you want to tag global variables.
323 Tags for subroutines are named @samp{@var{package}::@var{sub}}. The
324 name for subroutines defined in the default package is
325 @samp{main::@var{sub}}.
328 In PHP code, tags are functions, classes and defines. When using the
329 @samp{--members} option, vars are tags too.
332 In PostScript code, the tags are the functions.
335 In Prolog code, tags are predicates and rules at the beginning of
339 In Python code, @code{def} or @code{class} at the beginning of a line
343 You can also generate tags based on regexp matching (@pxref{Etags
344 Regexps}) to handle other formats and languages.
346 @node Create Tags Table
347 @subsection Creating Tags Tables
348 @cindex @code{etags} program
350 The @code{etags} program is used to create a tags table file. It knows
351 the syntax of several languages, as described in
353 the previous section.
358 Here is how to run @code{etags}:
361 etags @var{inputfiles}@dots{}
365 The @code{etags} program reads the specified files, and writes a tags
366 table named @file{TAGS} in the current working directory.
368 If the specified files don't exist, @code{etags} looks for
369 compressed versions of them and uncompresses them to read them. Under
370 MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz}
371 if it is given @samp{mycode.c} on the command line and @file{mycode.c}
374 @code{etags} recognizes the language used in an input file based on
375 its file name and contents. You can specify the language with the
376 @samp{--language=@var{name}} option, described below.
378 If the tags table data become outdated due to changes in the files
379 described in the table, the way to update the tags table is the same
380 way it was made in the first place. If the tags table fails to record
381 a tag, or records it for the wrong file, then Emacs cannot possibly
382 find its definition until you update the tags table. However, if the
383 position recorded in the tags table becomes a little bit wrong (due to
384 other editing), the worst consequence is a slight delay in finding the
385 tag. Even if the stored position is very far wrong, Emacs will still
386 find the tag, after searching most of the file for it. That delay is
387 hardly noticeable with today's computers.
389 Thus, there is no need to update the tags table after each edit.
390 You should update a tags table when you define new tags that you want
391 to have listed, or when you move tag definitions from one file to
392 another, or when changes become substantial.
394 One tags table can virtually include another. Specify the included
395 tags file name with the @samp{--include=@var{file}} option when
396 creating the file that is to include it. The latter file then acts as
397 if it covered all the source files specified in the included file, as
398 well as the files it directly contains.
400 If you specify the source files with relative file names when you run
401 @code{etags}, the tags file will contain file names relative to the
402 directory where the tags file was initially written. This way, you can
403 move an entire directory tree containing both the tags file and the
404 source files, and the tags file will still refer correctly to the source
405 files. If the tags file is in @file{/dev}, however, the file names are
406 made relative to the current working directory. This is useful, for
407 example, when writing the tags to @file{/dev/stdout}.
409 If you specify absolute file names as arguments to @code{etags}, then
410 the tags file will contain absolute file names. This way, the tags file
411 will still refer to the same files even if you move it, as long as the
412 source files remain in the same place. Absolute file names start with
413 @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
415 When you want to make a tags table from a great number of files, you
416 may have problems listing them on the command line, because some systems
417 have a limit on its length. The simplest way to circumvent this limit
418 is to tell @code{etags} to read the file names from its standard input,
419 by typing a dash in place of the file names, like this:
422 find . -name "*.[chCH]" -print | etags -
425 Use the option @samp{--language=@var{name}} to specify the language
426 explicitly. You can intermix these options with file names; each one
427 applies to the file names that follow it. Specify
428 @samp{--language=auto} to tell @code{etags} to resume guessing the
429 language from the file names and file contents. Specify
430 @samp{--language=none} to turn off language-specific processing
431 entirely; then @code{etags} recognizes tags by regexp matching alone
432 (@pxref{Etags Regexps}).
434 The option @samp{--parse-stdin=@var{file}} is mostly useful when
435 calling @code{etags} from programs. It can be used (only once) in
436 place of a file name on the command line. @code{Etags} will read from
437 standard input and mark the produced tags as belonging to the file
440 @samp{etags --help} outputs the list of the languages @code{etags}
441 knows, and the file name rules for guessing the language. It also prints
442 a list of all the available @code{etags} options, together with a short
443 explanation. If followed by one or more @samp{--language=@var{lang}}
444 options, it outputs detailed information about how tags are generated for
448 @subsection Etags Regexps
450 The @samp{--regex} option provides a general way of recognizing tags
451 based on regexp matching. You can freely intermix this option with
452 file names, and each one applies to the source files that follow it.
453 If you specify multiple @samp{--regex} options, all of them are used
454 in parallel. The syntax is:
457 --regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers}
460 The essential part of the option value is @var{tagregexp}, the
461 regexp for matching tags. It is always used anchored, that is, it
462 only matches at the beginning of a line. If you want to allow
463 indented tags, use a regexp that matches initial whitespace; start it
466 In these regular expressions, @samp{\} quotes the next character, and
467 all the GCC character escape sequences are supported (@samp{\a} for
468 bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for
469 escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for
470 carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab).
472 Ideally, @var{tagregexp} should not match more characters than are
473 needed to recognize what you want to tag. If the syntax requires you
474 to write @var{tagregexp} so it matches more characters beyond the tag
475 itself, you should add a @var{nameregexp}, to pick out just the tag.
476 This will enable Emacs to find tags more accurately and to do
477 completion on tag names more reliably. You can find some examples
480 The @var{modifiers} are a sequence of zero or more characters that
481 modify the way @code{etags} does the matching. A regexp with no
482 modifiers is applied sequentially to each line of the input file, in a
483 case-sensitive way. The modifiers and their meanings are:
487 Ignore case when matching this regexp.
489 Match this regular expression against the whole file, so that
490 multi-line matches are possible.
492 Match this regular expression against the whole file, and allow
493 @samp{.} in @var{tagregexp} to match newlines.
496 The @samp{-R} option cancels all the regexps defined by preceding
497 @samp{--regex} options. It too applies to the file names following
498 it. Here's an example:
501 etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
502 bar.ber -R --lang=lisp los.er
506 Here @code{etags} chooses the parsing language for @file{voo.doo} and
507 @file{bar.ber} according to their contents. @code{etags} also uses
508 @var{reg1} to recognize additional tags in @file{voo.doo}, and both
509 @var{reg1} and @var{reg2} to recognize additional tags in
510 @file{bar.ber}. @var{reg1} is checked against each line of
511 @file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while
512 @var{reg2} is checked against the whole @file{bar.ber} file,
513 permitting multi-line matches, in a case-sensitive way. @code{etags}
514 uses only the Lisp tags rules, with no user-specified regexp matching,
515 to recognize tags in @file{los.er}.
517 You can restrict a @samp{--regex} option to match only files of a
518 given language by using the optional prefix @var{@{language@}}.
519 (@samp{etags --help} prints the list of languages recognized by
520 @code{etags}.) This is particularly useful when storing many
521 predefined regular expressions for @code{etags} in a file. The
522 following example tags the @code{DEFVAR} macros in the Emacs source
523 files, for the C language only:
526 --regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
530 When you have complex regular expressions, you can store the list of
531 them in a file. The following option syntax instructs @code{etags} to
532 read two files of regular expressions. The regular expressions
533 contained in the second file are matched without regard to case.
536 --regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file}
540 A regex file for @code{etags} contains one regular expression per
541 line. Empty lines, and lines beginning with space or tab are ignored.
542 When the first character in a line is @samp{@@}, @code{etags} assumes
543 that the rest of the line is the name of another file of regular
544 expressions; thus, one such file can include another file. All the
545 other lines are taken to be regular expressions. If the first
546 non-whitespace text on the line is @samp{--}, that line is a comment.
548 For example, we can create a file called @samp{emacs.tags} with the
552 -- This is for GNU Emacs C source files
553 @{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
557 and then use it like this:
560 etags --regex=@@emacs.tags *.[ch] */*.[ch]
563 Here are some more examples. The regexps are quoted to protect them
564 from shell interpretation.
572 etags --language=none \
573 --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
574 --regex='/###key \(.*\)/\1/' \
575 --regex='/[ \t]*global[ \t].*/' \
580 Note that tags are not generated for scripts, so that you have to add
581 a line by yourself of the form @samp{###key @var{scriptname}} if you
588 etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
595 etags --language=none \
596 --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
597 --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
598 \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
602 @node Select Tags Table
603 @subsection Selecting a Tags Table
605 @vindex tags-file-name
606 @findex visit-tags-table
607 Emacs has at any time one @dfn{selected} tags table, and all the
608 commands for working with tags tables use the selected one. To select
609 a tags table, type @kbd{M-x visit-tags-table}, which reads the tags
610 table file name as an argument, with @file{TAGS} in the default
611 directory as the default.
613 Emacs does not actually read in the tags table contents until you
614 try to use them; all @code{visit-tags-table} does is store the file
615 name in the variable @code{tags-file-name}, and setting the variable
616 yourself is just as good. The variable's initial value is @code{nil};
617 that value tells all the commands for working with tags tables that
618 they must ask for a tags table file name to use.
620 Using @code{visit-tags-table} when a tags table is already loaded
621 gives you a choice: you can add the new tags table to the current list
622 of tags tables, or start a new list. The tags commands use all the tags
623 tables in the current list. If you start a new list, the new tags table
624 is used @emph{instead} of others. If you add the new table to the
625 current list, it is used @emph{as well as} the others.
627 @vindex tags-table-list
628 You can specify a precise list of tags tables by setting the variable
629 @code{tags-table-list} to a list of strings, like this:
631 @c keep this on two lines for formatting in smallbook
634 (setq tags-table-list
635 '("~/emacs" "/usr/local/lib/emacs/src"))
640 This tells the tags commands to look at the @file{TAGS} files in your
641 @file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
642 directory. The order depends on which file you are in and which tags
643 table mentions that file, as explained above.
645 Do not set both @code{tags-file-name} and @code{tags-table-list}.
648 @subsection Finding a Tag
650 The most important thing that a tags table enables you to do is to find
651 the definition of a specific tag.
654 @item M-.@: @var{tag} @key{RET}
655 Find first definition of @var{tag} (@code{find-tag}).
657 Find next alternate definition of last tag specified.
659 Go back to previous tag found.
660 @item C-M-. @var{pattern} @key{RET}
661 Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
663 Find the next tag whose name matches the last pattern used.
664 @item C-x 4 .@: @var{tag} @key{RET}
665 Find first definition of @var{tag}, but display it in another window
666 (@code{find-tag-other-window}).
667 @item C-x 5 .@: @var{tag} @key{RET}
668 Find first definition of @var{tag}, and create a new frame to select the
669 buffer (@code{find-tag-other-frame}).
671 Pop back to where you previously invoked @kbd{M-.} and friends.
676 @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
677 a specified tag. It searches through the tags table for that tag, as a
678 string, and then uses the tags table info to determine the file that the
679 definition is in and the approximate character position in the file of
680 the definition. Then @code{find-tag} visits that file, moves point to
681 the approximate character position, and searches ever-increasing
682 distances away to find the tag definition.
684 If an empty argument is given (just type @key{RET}), the balanced
685 expression in the buffer before or around point is used as the
686 @var{tag} argument. @xref{Expressions}.
688 You don't need to give @kbd{M-.} the full name of the tag; a part
689 will do. This is because @kbd{M-.} finds tags in the table which
690 contain @var{tag} as a substring. However, it prefers an exact match
691 to a substring match. To find other tags that match the same
692 substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
693 M-.}; this does not read a tag name, but continues searching the tags
694 table's text for another tag containing the same substring last used.
695 If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier
696 alternative to @kbd{C-u M-.}.
699 @findex find-tag-other-window
701 @findex find-tag-other-frame
702 Like most commands that can switch buffers, @code{find-tag} has a
703 variant that displays the new buffer in another window, and one that
704 makes a new frame for it. The former is @w{@kbd{C-x 4 .}}, which invokes
705 the command @code{find-tag-other-window}. The latter is @w{@kbd{C-x 5 .}},
706 which invokes @code{find-tag-other-frame}.
708 To move back to places you've found tags recently, use @kbd{C-u -
709 M-.}; more generally, @kbd{M-.} with a negative numeric argument. This
710 command can take you to another buffer. @w{@kbd{C-x 4 .}} with a negative
711 argument finds the previous tag location in another window.
715 @vindex find-tag-marker-ring-length
716 As well as going back to places you've found tags recently, you can go
717 back to places @emph{from where} you found them. Use @kbd{M-*}, which
718 invokes the command @code{pop-tag-mark}, for this. Typically you would
719 find and study the definition of something with @kbd{M-.} and then
720 return to where you were with @kbd{M-*}.
722 Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
723 a depth determined by the variable @code{find-tag-marker-ring-length}.
725 @findex find-tag-regexp
727 The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
728 match a specified regular expression. It is just like @kbd{M-.} except
729 that it does regexp matching instead of substring matching.
732 @subsection Searching and Replacing with Tags Tables
733 @cindex search and replace in multiple files
734 @cindex multiple-file search and replace
736 The commands in this section visit and search all the files listed
737 in the selected tags table, one by one. For these commands, the tags
738 table serves only to specify a sequence of files to search. These
739 commands scan the list of tags tables starting with the first tags
740 table (if any) that describes the current file, proceed from there to
741 the end of the list, and then scan from the beginning of the list
742 until they have covered all the tables in the list.
745 @item M-x tags-search @key{RET} @var{regexp} @key{RET}
746 Search for @var{regexp} through the files in the selected tags
748 @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
749 Perform a @code{query-replace-regexp} on each file in the selected tags table.
751 Restart one of the commands above, from the current location of point
752 (@code{tags-loop-continue}).
756 @kbd{M-x tags-search} reads a regexp using the minibuffer, then
757 searches for matches in all the files in the selected tags table, one
758 file at a time. It displays the name of the file being searched so you
759 can follow its progress. As soon as it finds an occurrence,
760 @code{tags-search} returns.
763 @findex tags-loop-continue
764 Having found one match, you probably want to find all the rest. To find
765 one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
766 @code{tags-search}. This searches the rest of the current buffer, followed
767 by the remaining files of the tags table.@refill
769 @findex tags-query-replace
770 @kbd{M-x tags-query-replace} performs a single
771 @code{query-replace-regexp} through all the files in the tags table. It
772 reads a regexp to search for and a string to replace with, just like
773 ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
774 tags-search}, but repeatedly, processing matches according to your
775 input. @xref{Replace}, for more information on query replace.
777 @vindex tags-case-fold-search
778 @cindex case-sensitivity and tags search
779 You can control the case-sensitivity of tags search commands by
780 customizing the value of the variable @code{tags-case-fold-search}. The
781 default is to use the same setting as the value of
782 @code{case-fold-search} (@pxref{Search Case}).
784 It is possible to get through all the files in the tags table with a
785 single invocation of @kbd{M-x tags-query-replace}. But often it is
786 useful to exit temporarily, which you can do with any input event that
787 has no special query replace meaning. You can resume the query replace
788 subsequently by typing @kbd{M-,}; this command resumes the last tags
789 search or replace command that you did.
791 The commands in this section carry out much broader searches than the
792 @code{find-tag} family. The @code{find-tag} commands search only for
793 definitions of tags that match your substring or regexp. The commands
794 @code{tags-search} and @code{tags-query-replace} find every occurrence
795 of the regexp, as ordinary search commands and replace commands do in
798 These commands create buffers only temporarily for the files that they
799 have to search (those which are not already visited in Emacs buffers).
800 Buffers in which no match is found are quickly killed; the others
803 It may have struck you that @code{tags-search} is a lot like
804 @code{grep}. You can also run @code{grep} itself as an inferior of
805 Emacs and have Emacs show you the matching lines one by one.
806 @xref{Grep Searching}.
809 @subsection Tags Table Inquiries
812 @item M-x list-tags @key{RET} @var{file} @key{RET}
813 Display a list of the tags defined in the program file @var{file}.
814 @item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
815 Display a list of all tags matching @var{regexp}.
819 @kbd{M-x list-tags} reads the name of one of the files described by
820 the selected tags table, and displays a list of all the tags defined in
821 that file. The ``file name'' argument is really just a string to
822 compare against the file names recorded in the tags table; it is read as
823 a string rather than as a file name. Therefore, completion and
824 defaulting are not available, and you must enter the file name the same
825 way it appears in the tags table. Do not include a directory as part of
826 the file name unless the file name recorded in the tags table includes a
830 @vindex tags-apropos-verbose
831 @kbd{M-x tags-apropos} is like @code{apropos} for tags
832 (@pxref{Apropos}). It finds all the tags in the selected tags table
833 whose entries match @var{regexp}, and displays them. If the variable
834 @code{tags-apropos-verbose} is non-@code{nil}, it displays the names
835 of the tags files together with the tag names.
837 @vindex tags-tag-face
838 @vindex tags-apropos-additional-actions
839 You can customize the appearance of the output by setting the
840 variable @code{tags-tag-face} to a face. You can display additional
841 output with @kbd{M-x tags-apropos} by customizing the variable
842 @code{tags-apropos-additional-actions}---see its documentation for
845 You can also use the collection of tag names to complete a symbol
846 name in the buffer. @xref{Symbol Completion}.
849 arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb