@c This is part of the Emacs manual.@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,@c 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.@c See file emacs.texi for copying conditions.@node Maintaining, Abbrevs, Building, Top@chapter Maintaining Large Programs This chapter describes Emacs features for maintaining largeprograms. The version control features (@pxref{Version Control}) arealso particularly useful for this purpose.@menu* Change Log:: Maintaining a change history for your program.* Format of ChangeLog:: What the change log file looks like.* Tags:: Go direct to any function in your program in one command. Tags remembers which file it is in.@end menu@node Change Log@section Change Logs A change log file contains a chronological record of when and why youhave changed a program, consisting of a sequence of entries describingindividual changes. Normally it is kept in a file called@file{ChangeLog} in the same directory as the file you are editing, orone of its parent directories. A single @file{ChangeLog} file canrecord changes for all the files in its directory and all itssubdirectories.@cindex change log@kindex C-x 4 a@findex add-change-log-entry-other-window The Emacs command @kbd{C-x 4 a} adds a new entry to the change logfile for the file you are editing(@code{add-change-log-entry-other-window}). If that file is actuallya backup file, it makes an entry appropriate for the file'sparent---that is useful for making log entries for functions thathave been deleted in the current version. @kbd{C-x 4 a} visits the change log file and creates a new entryunless the most recent entry is for today's date and your name. Italso creates a new item for the current file. For many languages, itcan even guess the name of the function or other object that waschanged.@vindex add-log-keep-changes-together When the variable @code{add-log-keep-changes-together} isnon-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the filerather than starting a new item.@vindex add-log-always-start-new-record If @code{add-log-always-start-new-record} is non-@code{nil},@kbd{C-x 4 a} always makes a new entry, even if the last entrywas made by you and on the same date.@vindex change-log-version-info-enabled@vindex change-log-version-number-regexp-list@cindex file version in change log entries If the value of the variable @code{change-log-version-info-enabled}is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to thechange log entry. It finds the version number by searching the firstten percent of the file, using regular expressions from the variable@code{change-log-version-number-regexp-list}.@cindex Change Log mode@findex change-log-mode The change log file is visited in Change Log mode. In this majormode, each bunch of grouped items counts as one paragraph, and eachentry is considered a page. This facilitates editing the entries.@kbd{C-j} and auto-fill indent each new line like the previous line;this is convenient for entering the contents of an entry.@findex change-log-merge You can use the command @kbd{M-x change-log-merge} to merge otherlog files into a buffer in Change Log Mode, preserving the dateordering of entries. Version control systems are another way to keep track of changes in yourprogram and keep a change log. @xref{Log Buffer}.@node Format of ChangeLog@section Format of ChangeLog A change log entry starts with a header line that contains the currentdate, your name, and your email address (taken from the variable@code{add-log-mailing-address}). Aside from these header lines, everyline in the change log starts with a space or a tab. The bulk of theentry consists of @dfn{items}, each of which starts with a line startingwith whitespace and a star. Here are two entries, both dated in May1993, with two items and one item respectively.@iftex@medbreak@end iftex@smallexample1993-05-25 Richard Stallman <rms@@gnu.org> * man.el: Rename symbols `man-*' to `Man-*'. (manual-entry): Make prompt string clearer. * simple.el (blink-matching-paren-distance): Change default to 12,000.1993-05-24 Richard Stallman <rms@@gnu.org> * vc.el (minor-mode-map-alist): Don't use it if it's void. (vc-cancel-version): Doc fix.@end smallexample One entry can describe several changes; each change should have itsown item, or its own line in an item. Normally there should be ablank line between items. When items are related (parts of the samechange, in different places), group them by leaving no blank linebetween them. You should put a copyright notice and permission notice at theend of the change log file. Here is an example:@exampleCopyright 1997, 1998 Free Software Foundation, Inc.Copying and distribution of this file, with or without modification, arepermitted provided the copyright notice and this notice are preserved.@end example@noindentOf course, you should substitute the proper years and copyright holder.@node Tags@section Tags Tables@cindex tags table A @dfn{tags table} is a description of how a multi-file program isbroken up into files. It lists the names of the component files and thenames and positions of the functions (or other named subunits) in eachfile. Grouping the related files makes it possible to search or replacethrough all the files with one command. Recording the function namesand positions makes possible the @kbd{M-.} command which finds thedefinition of a function by looking up which of the files it is in. Tags tables are stored in files called @dfn{tags table files}. Theconventional name for a tags table file is @file{TAGS}. Each entry in the tags table records the name of one tag, the name of thefile that the tag is defined in (implicitly), and the position in thatfile of the tag's definition. When a file parsed by @code{etags} isgenerated from a different source file, like a C file generated from aCweb source file, the tags of the parsed file reference the sourcefile. Just what names from the described files are recorded in the tags tabledepends on the programming language of the described file. Theynormally include all file names, functions and subroutines, and mayalso include global variables, data types, and anything elseconvenient. Each name recorded is called a @dfn{tag}.@cindex C++ class browser, tags@cindex tags, C++@cindex class browser, C++@cindex Ebrowse See also the Ebrowse facility, which is tailored for C++.@xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}.@menu* Tag Syntax:: Tag syntax for various types of code and text files.* Create Tags Table:: Creating a tags table with @code{etags}.* Etags Regexps:: Create arbitrary tags using regular expressions.* Select Tags Table:: How to visit a tags table.* Find Tag:: Commands to find the definition of a specific tag.* Tags Search:: Using a tags table for searching and replacing.* List Tags:: Listing and finding tags defined in a file.@end menu@node Tag Syntax@subsection Source File Tag Syntax Here is how tag syntax is defined for the most popular languages:@itemize @bullet@itemIn C code, any C function or typedef is a tag, and so are definitions of@code{struct}, @code{union} and @code{enum}.@code{#define} macro definitions and @code{enum} constants are alsotags, unless you specify @samp{--no-defines} when making the tags table.Similarly, global variables are tags, unless you specify@samp{--no-globals}. Use of @samp{--no-globals} and @samp{--no-defines}can make the tags table file much smaller.You can tag function declarations and external variables in additionto function definitions by giving the @samp{--declarations} option to@code{etags}. You can tag struct members with the @samp{--members}option.@itemIn C++ code, in addition to all the tag constructs of C code, memberfunctions are also recognized, and optionally member variables if youuse the @samp{--members} option. Tags for variables and functions inclasses are named @samp{@var{class}::@var{variable}} and@samp{@var{class}::@var{function}}. @code{operator} definitions havetag names like @samp{operator+}.@itemIn Java code, tags include all the constructs recognized in C++, plusthe @code{interface}, @code{extends} and @code{implements} constructs.Tags for variables and functions in classes are named@samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.@itemIn La@TeX{} text, the argument of any of the commands @code{\chapter},@code{\section}, @code{\subsection}, @code{\subsubsection},@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite},@code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry},@code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand},@code{\newenvironment} or @code{\renewenvironment} is a tag.@refillOther commands can make tags as well, if you specify them in theenvironment variable @env{TEXTAGS} before invoking @code{etags}. Thevalue of this environment variable should be a colon-separated list ofcommand names. For example,@exampleTEXTAGS="mycommand:myothercommand"export TEXTAGS@end example@noindentspecifies (using Bourne shell syntax) that the commands@samp{\mycommand} and @samp{\myothercommand} also define tags.@itemIn Lisp code, any function defined with @code{defun}, any variabledefined with @code{defvar} or @code{defconst}, and in general the firstargument of any expression that starts with @samp{(def} in column zero isa tag.@itemIn Scheme code, tags include anything defined with @code{def} or with aconstruct whose name starts with @samp{def}. They also include variablesset with @code{set!} at top level in the file.@end itemize Several other languages are also supported:@itemize @bullet@itemIn Ada code, functions, procedures, packages, tasks and types aretags. Use the @samp{--packages-only} option to create tags forpackages only.In Ada, the same name can be used for different kinds of entity(e.g.@:, for a procedure and for a function). Also, for things likepackages, procedures and functions, there is the spec (i.e.@: theinterface) and the body (i.e.@: the implementation). To make iteasier to pick the definition you want, Ada tag name have suffixesindicating the type of entity:@table @samp@item /bpackage body.@item /ffunction.@item /ktask.@item /pprocedure.@item /spackage spec.@item /ttype.@end table Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will godirectly to the body of the package @code{bidule}, while @kbd{M-xfind-tag @key{RET} bidule @key{RET}} will just search for any tag@code{bidule}.@itemIn assembler code, labels appearing at the beginning of a line,followed by a colon, are tags.@itemIn Bison or Yacc input files, each rule defines as a tag the nonterminalit constructs. The portions of the file that contain C code are parsedas C code.@itemIn Cobol code, tags are paragraph names; that is, any word starting incolumn 8 and followed by a period.@itemIn Erlang code, the tags are the functions, records and macros definedin the file.@itemIn Fortran code, functions, subroutines and block data are tags.@itemIn HTML input files, the tags are the @code{title} and the @code{h1},@code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchorsand all occurrences of @code{id=}.@itemIn Lua input files, all functions are tags.@itemIn makefiles, targets are tags; additionally, variables are tagsunless you specify @samp{--no-globals}.@itemIn Objective C code, tags include Objective C definitions for classes,class categories, methods and protocols. Tags for variables andfunctions in classes are named @samp{@var{class}::@var{variable}} and@samp{@var{class}::@var{function}}.@itemIn Pascal code, the tags are the functions and procedures defined inthe file.@itemIn Perl code, the tags are the packages, subroutines and variablesdefined by the @code{package}, @code{sub}, @code{my} and @code{local}keywords. Use @samp{--globals} if you want to tag global variables.Tags for subroutines are named @samp{@var{package}::@var{sub}}. Thename for subroutines defined in the default package is@samp{main::@var{sub}}.@itemIn PHP code, tags are functions, classes and defines. When using the@samp{--members} option, vars are tags too.@itemIn PostScript code, the tags are the functions.@itemIn Prolog code, tags are predicates and rules at the beginning ofline.@itemIn Python code, @code{def} or @code{class} at the beginning of a linegenerate a tag.@end itemize You can also generate tags based on regexp matching (@pxref{EtagsRegexps}) to handle other formats and languages.@node Create Tags Table@subsection Creating Tags Tables@cindex @code{etags} program The @code{etags} program is used to create a tags table file. It knowsthe syntax of several languages, as described in@iftexthe previous section.@end iftex@ifinfo@ref{Tag Syntax}.@end ifinfoHere is how to run @code{etags}:@exampleetags @var{inputfiles}@dots{}@end example@noindentThe @code{etags} program reads the specified files, and writes a tagstable named @file{TAGS} in the current working directory. If the specified files don't exist, @code{etags} looks forcompressed versions of them and uncompresses them to read them. UnderMS-DOS, @code{etags} also looks for file names like @file{mycode.cgz}if it is given @samp{mycode.c} on the command line and @file{mycode.c}does not exist. @code{etags} recognizes the language used in an input file based onits file name and contents. You can specify the language with the@samp{--language=@var{name}} option, described below. If the tags table data become outdated due to changes in the filesdescribed in the table, the way to update the tags table is the sameway it was made in the first place. If the tags table fails to recorda tag, or records it for the wrong file, then Emacs cannot possiblyfind its definition until you update the tags table. However, if theposition recorded in the tags table becomes a little bit wrong (due toother editing), the worst consequence is a slight delay in finding thetag. Even if the stored position is very far wrong, Emacs will stillfind the tag, after searching most of the file for it. That delay ishardly noticeable with today's computers. Thus, there is no need to update the tags table after each edit.You should update a tags table when you define new tags that you wantto have listed, or when you move tag definitions from one file toanother, or when changes become substantial. One tags table can virtually include another. Specify the includedtags file name with the @samp{--include=@var{file}} option whencreating the file that is to include it. The latter file then acts asif it covered all the source files specified in the included file, aswell as the files it directly contains. If you specify the source files with relative file names when you run@code{etags}, the tags file will contain file names relative to thedirectory where the tags file was initially written. This way, you canmove an entire directory tree containing both the tags file and thesource files, and the tags file will still refer correctly to the sourcefiles. If the tags file is in @file{/dev}, however, the file names aremade relative to the current working directory. This is useful, forexample, when writing the tags to @file{/dev/stdout}. If you specify absolute file names as arguments to @code{etags}, thenthe tags file will contain absolute file names. This way, the tags filewill still refer to the same files even if you move it, as long as thesource files remain in the same place. Absolute file names start with@samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows. When you want to make a tags table from a great number of files, youmay have problems listing them on the command line, because some systemshave a limit on its length. The simplest way to circumvent this limitis to tell @code{etags} to read the file names from its standard input,by typing a dash in place of the file names, like this:@smallexamplefind . -name "*.[chCH]" -print | etags -@end smallexample Use the option @samp{--language=@var{name}} to specify the languageexplicitly. You can intermix these options with file names; each oneapplies to the file names that follow it. Specify@samp{--language=auto} to tell @code{etags} to resume guessing thelanguage from the file names and file contents. Specify@samp{--language=none} to turn off language-specific processingentirely; then @code{etags} recognizes tags by regexp matching alone(@pxref{Etags Regexps}). The option @samp{--parse-stdin=@var{file}} is mostly useful whencalling @code{etags} from programs. It can be used (only once) inplace of a file name on the command line. @code{Etags} will read fromstandard input and mark the produced tags as belonging to the file@var{file}. @samp{etags --help} outputs the list of the languages @code{etags}knows, and the file name rules for guessing the language. It also printsa list of all the available @code{etags} options, together with a shortexplanation. If followed by one or more @samp{--language=@var{lang}}options, it outputs detailed information about how tags are generated for@var{lang}.@node Etags Regexps@subsection Etags Regexps The @samp{--regex} option provides a general way of recognizing tagsbased on regexp matching. You can freely intermix this option withfile names, and each one applies to the source files that follow it.If you specify multiple @samp{--regex} options, all of them are usedin parallel. The syntax is:@smallexample--regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers}@end smallexample The essential part of the option value is @var{tagregexp}, theregexp for matching tags. It is always used anchored, that is, itonly matches at the beginning of a line. If you want to allowindented tags, use a regexp that matches initial whitespace; start itwith @samp{[ \t]*}. In these regular expressions, @samp{\} quotes the next character, andall the GCC character escape sequences are supported (@samp{\a} forbell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} forescape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} forcarriage return, @samp{\t} for tab, and @samp{\v} for vertical tab). Ideally, @var{tagregexp} should not match more characters than areneeded to recognize what you want to tag. If the syntax requires youto write @var{tagregexp} so it matches more characters beyond the tagitself, you should add a @var{nameregexp}, to pick out just the tag.This will enable Emacs to find tags more accurately and to docompletion on tag names more reliably. You can find some examplesbelow. The @var{modifiers} are a sequence of zero or more characters thatmodify the way @code{etags} does the matching. A regexp with nomodifiers is applied sequentially to each line of the input file, in acase-sensitive way. The modifiers and their meanings are:@table @samp@item iIgnore case when matching this regexp.@item mMatch this regular expression against the whole file, so thatmulti-line matches are possible.@item sMatch this regular expression against the whole file, and allow@samp{.} in @var{tagregexp} to match newlines.@end table The @samp{-R} option cancels all the regexps defined by preceding@samp{--regex} options. It too applies to the file names followingit. Here's an example:@smallexampleetags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \ bar.ber -R --lang=lisp los.er@end smallexample@noindentHere @code{etags} chooses the parsing language for @file{voo.doo} and@file{bar.ber} according to their contents. @code{etags} also uses@var{reg1} to recognize additional tags in @file{voo.doo}, and both@var{reg1} and @var{reg2} to recognize additional tags in@file{bar.ber}. @var{reg1} is checked against each line of@file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while@var{reg2} is checked against the whole @file{bar.ber} file,permitting multi-line matches, in a case-sensitive way. @code{etags}uses only the Lisp tags rules, with no user-specified regexp matching,to recognize tags in @file{los.er}. You can restrict a @samp{--regex} option to match only files of agiven language by using the optional prefix @var{@{language@}}.(@samp{etags --help} prints the list of languages recognized by@code{etags}.) This is particularly useful when storing manypredefined regular expressions for @code{etags} in a file. Thefollowing example tags the @code{DEFVAR} macros in the Emacs sourcefiles, for the C language only:@smallexample--regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'@end smallexample@noindentWhen you have complex regular expressions, you can store the list ofthem in a file. The following option syntax instructs @code{etags} toread two files of regular expressions. The regular expressionscontained in the second file are matched without regard to case.@smallexample--regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file}@end smallexample@noindentA regex file for @code{etags} contains one regular expression perline. Empty lines, and lines beginning with space or tab are ignored.When the first character in a line is @samp{@@}, @code{etags} assumesthat the rest of the line is the name of another file of regularexpressions; thus, one such file can include another file. All theother lines are taken to be regular expressions. If the firstnon-whitespace text on the line is @samp{--}, that line is a comment. For example, we can create a file called @samp{emacs.tags} with thefollowing contents:@smallexample -- This is for GNU Emacs C source files@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/@end smallexample@noindentand then use it like this:@smallexampleetags --regex=@@emacs.tags *.[ch] */*.[ch]@end smallexample Here are some more examples. The regexps are quoted to protect themfrom shell interpretation.@itemize @bullet@itemTag Octave files:@smallexampleetags --language=none \ --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \ --regex='/###key \(.*\)/\1/' \ --regex='/[ \t]*global[ \t].*/' \ *.m@end smallexample@noindentNote that tags are not generated for scripts, so that you have to adda line by yourself of the form @samp{###key @var{scriptname}} if youwant to jump to it.@itemTag Tcl files:@smallexampleetags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl@end smallexample@itemTag VHDL files:@smallexampleetags --language=none \ --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \ --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\ \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'@end smallexample@end itemize@node Select Tags Table@subsection Selecting a Tags Table@vindex tags-file-name@findex visit-tags-table Emacs has at any time one @dfn{selected} tags table, and all thecommands for working with tags tables use the selected one. To selecta tags table, type @kbd{M-x visit-tags-table}, which reads the tagstable file name as an argument, with @file{TAGS} in the defaultdirectory as the default. Emacs does not actually read in the tags table contents until youtry to use them; all @code{visit-tags-table} does is store the filename in the variable @code{tags-file-name}, and setting the variableyourself is just as good. The variable's initial value is @code{nil};that value tells all the commands for working with tags tables thatthey must ask for a tags table file name to use. Using @code{visit-tags-table} when a tags table is already loadedgives you a choice: you can add the new tags table to the current listof tags tables, or start a new list. The tags commands use all the tagstables in the current list. If you start a new list, the new tags tableis used @emph{instead} of others. If you add the new table to thecurrent list, it is used @emph{as well as} the others.@vindex tags-table-list You can specify a precise list of tags tables by setting the variable@code{tags-table-list} to a list of strings, like this:@c keep this on two lines for formatting in smallbook@example@group(setq tags-table-list '("~/emacs" "/usr/local/lib/emacs/src"))@end group@end example@noindentThis tells the tags commands to look at the @file{TAGS} files in your@file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}directory. The order depends on which file you are in and which tagstable mentions that file, as explained above. Do not set both @code{tags-file-name} and @code{tags-table-list}.@node Find Tag@subsection Finding a Tag The most important thing that a tags table enables you to do is to findthe definition of a specific tag.@table @kbd@item M-.@: @var{tag} @key{RET}Find first definition of @var{tag} (@code{find-tag}).@item C-u M-.Find next alternate definition of last tag specified.@item C-u - M-.Go back to previous tag found.@item C-M-. @var{pattern} @key{RET}Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).@item C-u C-M-.Find the next tag whose name matches the last pattern used.@item C-x 4 .@: @var{tag} @key{RET}Find first definition of @var{tag}, but display it in another window(@code{find-tag-other-window}).@item C-x 5 .@: @var{tag} @key{RET}Find first definition of @var{tag}, and create a new frame to select thebuffer (@code{find-tag-other-frame}).@item M-*Pop back to where you previously invoked @kbd{M-.} and friends.@end table@kindex M-.@findex find-tag @kbd{M-.}@: (@code{find-tag}) is the command to find the definition ofa specified tag. It searches through the tags table for that tag, as astring, and then uses the tags table info to determine the file that thedefinition is in and the approximate character position in the file ofthe definition. Then @code{find-tag} visits that file, moves point tothe approximate character position, and searches ever-increasingdistances away to find the tag definition. If an empty argument is given (just type @key{RET}), the balancedexpression in the buffer before or around point is used as the@var{tag} argument. @xref{Expressions}. You don't need to give @kbd{M-.} the full name of the tag; a partwill do. This is because @kbd{M-.} finds tags in the table whichcontain @var{tag} as a substring. However, it prefers an exact matchto a substring match. To find other tags that match the samesubstring, give @code{find-tag} a numeric argument, as in @kbd{C-uM-.}; this does not read a tag name, but continues searching the tagstable's text for another tag containing the same substring last used.If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easieralternative to @kbd{C-u M-.}.@kindex C-x 4 .@findex find-tag-other-window@kindex C-x 5 .@findex find-tag-other-frame Like most commands that can switch buffers, @code{find-tag} has avariant that displays the new buffer in another window, and one thatmakes a new frame for it. The former is @w{@kbd{C-x 4 .}}, which invokesthe command @code{find-tag-other-window}. The latter is @w{@kbd{C-x 5 .}},which invokes @code{find-tag-other-frame}. To move back to places you've found tags recently, use @kbd{C-u -M-.}; more generally, @kbd{M-.} with a negative numeric argument. Thiscommand can take you to another buffer. @w{@kbd{C-x 4 .}} with a negativeargument finds the previous tag location in another window.@kindex M-*@findex pop-tag-mark@vindex find-tag-marker-ring-length As well as going back to places you've found tags recently, you can goback to places @emph{from where} you found them. Use @kbd{M-*}, whichinvokes the command @code{pop-tag-mark}, for this. Typically you wouldfind and study the definition of something with @kbd{M-.} and thenreturn to where you were with @kbd{M-*}. Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps toa depth determined by the variable @code{find-tag-marker-ring-length}.@findex find-tag-regexp@kindex C-M-. The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags thatmatch a specified regular expression. It is just like @kbd{M-.} exceptthat it does regexp matching instead of substring matching.@node Tags Search@subsection Searching and Replacing with Tags Tables@cindex search and replace in multiple files@cindex multiple-file search and replace The commands in this section visit and search all the files listedin the selected tags table, one by one. For these commands, the tagstable serves only to specify a sequence of files to search. Thesecommands scan the list of tags tables starting with the first tagstable (if any) that describes the current file, proceed from there tothe end of the list, and then scan from the beginning of the listuntil they have covered all the tables in the list.@table @kbd@item M-x tags-search @key{RET} @var{regexp} @key{RET}Search for @var{regexp} through the files in the selected tagstable.@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}Perform a @code{query-replace-regexp} on each file in the selected tags table.@item M-,Restart one of the commands above, from the current location of point(@code{tags-loop-continue}).@end table@findex tags-search @kbd{M-x tags-search} reads a regexp using the minibuffer, thensearches for matches in all the files in the selected tags table, onefile at a time. It displays the name of the file being searched so youcan follow its progress. As soon as it finds an occurrence,@code{tags-search} returns.@kindex M-,@findex tags-loop-continue Having found one match, you probably want to find all the rest. To findone more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the@code{tags-search}. This searches the rest of the current buffer, followedby the remaining files of the tags table.@refill@findex tags-query-replace @kbd{M-x tags-query-replace} performs a single@code{query-replace-regexp} through all the files in the tags table. Itreads a regexp to search for and a string to replace with, just likeordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-xtags-search}, but repeatedly, processing matches according to yourinput. @xref{Replace}, for more information on query replace.@vindex tags-case-fold-search@cindex case-sensitivity and tags search You can control the case-sensitivity of tags search commands bycustomizing the value of the variable @code{tags-case-fold-search}. Thedefault is to use the same setting as the value of@code{case-fold-search} (@pxref{Search Case}). It is possible to get through all the files in the tags table with asingle invocation of @kbd{M-x tags-query-replace}. But often it isuseful to exit temporarily, which you can do with any input event thathas no special query replace meaning. You can resume the query replacesubsequently by typing @kbd{M-,}; this command resumes the last tagssearch or replace command that you did. The commands in this section carry out much broader searches than the@code{find-tag} family. The @code{find-tag} commands search only fordefinitions of tags that match your substring or regexp. The commands@code{tags-search} and @code{tags-query-replace} find every occurrenceof the regexp, as ordinary search commands and replace commands do inthe current buffer. These commands create buffers only temporarily for the files that theyhave to search (those which are not already visited in Emacs buffers).Buffers in which no match is found are quickly killed; the otherscontinue to exist. It may have struck you that @code{tags-search} is a lot like@code{grep}. You can also run @code{grep} itself as an inferior ofEmacs and have Emacs show you the matching lines one by one.@xref{Grep Searching}.@node List Tags@subsection Tags Table Inquiries@table @kbd@item M-x list-tags @key{RET} @var{file} @key{RET}Display a list of the tags defined in the program file @var{file}.@item M-x tags-apropos @key{RET} @var{regexp} @key{RET}Display a list of all tags matching @var{regexp}.@end table@findex list-tags @kbd{M-x list-tags} reads the name of one of the files described bythe selected tags table, and displays a list of all the tags defined inthat file. The ``file name'' argument is really just a string tocompare against the file names recorded in the tags table; it is read asa string rather than as a file name. Therefore, completion anddefaulting are not available, and you must enter the file name the sameway it appears in the tags table. Do not include a directory as part ofthe file name unless the file name recorded in the tags table includes adirectory.@findex tags-apropos@vindex tags-apropos-verbose @kbd{M-x tags-apropos} is like @code{apropos} for tags(@pxref{Apropos}). It finds all the tags in the selected tags tablewhose entries match @var{regexp}, and displays them. If the variable@code{tags-apropos-verbose} is non-@code{nil}, it displays the namesof the tags files together with the tag names.@vindex tags-tag-face@vindex tags-apropos-additional-actions You can customize the appearance of the output by setting thevariable @code{tags-tag-face} to a face. You can display additionaloutput with @kbd{M-x tags-apropos} by customizing the variable@code{tags-apropos-additional-actions}---see its documentation fordetails. You can also use the collection of tag names to complete a symbolname in the buffer. @xref{Symbol Completion}.@ignore arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb@end ignore