@c This is part of the Emacs manual.@c Copyright (C) 1985,86,87,93,94,95,97,99,00,2001 Free Software Foundation, Inc.@c See file emacs.texi for copying conditions.@node Maintaining, Abbrevs, Building, Top@chapter Maintaining Programs@cindex Lisp editing@cindex C editing@cindex program editing This chapter describes Emacs features for maintaining programs. Theversion control features (@pxref{Version Control}) are alsoparticularly useful for this purpose.@menu* Change Log:: Maintaining a change history for your program.* Tags:: Go direct to any function in your program in one command. Tags remembers which file it is in.* Emerge:: A convenient way of merging two versions of a program.@end menu@node Change Log@section Change Logs@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. 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. 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. A change log entry starts with a header line that contains thecurrent date, your name, and your email address (taken from thevariable @code{user-mail-address}). Aside from these header lines,every line in the change log starts with a space or a tab. The bulkof the entry consists of @dfn{items}, each of which starts with a linestarting with whitespace and a star. Here are two entries, both datedin May 1993, each with two items:@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. Normally there should be a blank line between items. Whenitems are related (parts of the same change, in different places), groupthem by leaving no blank line between them. The second entry abovecontains two items grouped in this way. @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 option @code{add-log-keep-changes-together} isnon-@code{nil}, @kbd{C-x 4 a} adds to any existing entry for the filerather than starting a new entry.@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}.@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.@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.@findex change-log-redate@cindex converting change log date style Versions of Emacs before 20.1 used a different format for the time ofthe change log entry:@smallexampleFri May 25 11:23:23 1993 Richard Stallman <rms@@gnu.org>@end smallexample@noindentThe @kbd{M-x change-log-redate} command converts all the old-styledate entries in the change log file visited in the current buffer tothe new format, to make the file uniform in style. This is handy whenentries are contributed by many different people, some of whom use oldversions of Emacs. Version control systems are another way to keep track of changes in yourprogram and keep a change log. @xref{Log Buffer}.@ignore@c This is commented out because the command is specific@c to maintenance of Emacs itself.@node Authors@section @file{AUTHORS} files@cindex @file{AUTHORS} file Programs which have many contributors usually include a file named@file{AUTHORS} in their distribution, which lists the individualcontributions. Emacs has a special command for maintaining the@file{AUTHORS} file that is part of the Emacs distribution.@findex authors The @kbd{M-x authors} command prompts for the name of the root of theEmacs source directory. It then scans @file{ChangeLog} files and Lispsource files under that directory for information about authors ofindividual packages, and people who made changes in source files, andputs the information it gleans into a buffer named @samp{*Authors*}.You can then edit the contents of that buffer and merge it with theexisting @file{AUTHORS} file. Do not assume that this command finds all the contributors; don'tassume that a person not listed in the output was not a contributor.If you merged in someone's contribution and did not put his namein the change log, he won't show up in @kbd{M-x authors} either.@end ignore@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 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 only 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. Even thatdelay is hardly noticeable with today's computers. So 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 to another,or when changes become substantial. Normally there is no need to updatethe tags table after each edit, or even every day. 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 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} prints 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, prints 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 it with file names.If you specify multiple @samp{--regex} options, all of them are usedin parallel, but each one applies only to the source files that followit. 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 applies to the file names following it, asyou can see from the following 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 the commandsfor working with tags tables use the selected one. To select a tags table,type @kbd{M-x visit-tags-table}, which reads the tags table file name as anargument. The name @file{TAGS} in the default directory is used as thedefault file name. All this command does is store the file name in the variable@code{tags-file-name}. Emacs does not actually read in the tags tablecontents until you try to use them. Setting this variable yourself is justas good as using @code{visit-tags-table}. The variable's initial value is@code{nil}; that value tells all the commands for working with tags tablesthat they 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. When the tagscommands scan the list of tags tables, they don't always start at thebeginning of the list; they start with the first tags table (if any)that describes the current file, proceed from there to the end of thelist, and then scan from the beginning of the list until they havecovered all the tables in the list.@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 @kbd{C-x 4 .}, which invokesthe command @code{find-tag-other-window}. The latter is @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. @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 listed in theselected tags table, one by one. For these commands, the tags table servesonly to specify a sequence of files to search.@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. This worksmuch like running a compilation; finding the source locations of the@code{grep} matches works like finding the compilation errors.@xref{Compilation}.@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-actionsYou can customize the appearance of the output with the face@code{tags-tag-face}. You can display additional output with @kbd{M-xtags-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}.@node Emerge@section Merging Files with Emerge@cindex Emerge@cindex merging filesIt's not unusual for programmers to get their signals crossed and modifythe same program in two different directions. To recover from thisconfusion, you need to merge the two versions. Emerge makes thiseasier. See also @ref{Comparing Files}, for commands to comparein a more manual fashion, and @ref{Top, Ediff,, ediff, The Ediff Manual}.@menu* Overview of Emerge:: How to start Emerge. Basic concepts.* Submodes of Emerge:: Fast mode vs. Edit mode. Skip Prefers mode and Auto Advance mode.* State of Difference:: You do the merge by specifying state A or B for each difference.* Merge Commands:: Commands for selecting a difference, changing states of differences, etc.* Exiting Emerge:: What to do when you've finished the merge.* Combining in Emerge:: How to keep both alternatives for a difference.* Fine Points of Emerge:: Misc.@end menu@node Overview of Emerge@subsection Overview of EmergeTo start Emerge, run one of these four commands:@table @kbd@item M-x emerge-files@findex emerge-filesMerge two specified files.@item M-x emerge-files-with-ancestor@findex emerge-files-with-ancestorMerge two specified files, with reference to a common ancestor.@item M-x emerge-buffers@findex emerge-buffersMerge two buffers.@item M-x emerge-buffers-with-ancestor@findex emerge-buffers-with-ancestorMerge two buffers with reference to a common ancestor in a thirdbuffer.@end table@cindex merge buffer (Emerge)@cindex A and B buffers (Emerge) The Emerge commands compare two files or buffers, and display thecomparison in three buffers: one for each input text (the @dfn{A buffer}and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where mergingtakes place. The merge buffer shows the full merged text, not just thedifferences. Wherever the two input texts differ, you can choose whichone of them to include in the merge buffer. The Emerge commands that take input from existing buffers use only theaccessible portions of those buffers, if they are narrowed(@pxref{Narrowing}). If a common ancestor version is available, from which the two texts tobe merged were both derived, Emerge can use it to guess whichalternative is right. Wherever one current version agrees with theancestor, Emerge presumes that the other current version is a deliberatechange which should be kept in the merged version. Use the@samp{with-ancestor} commands if you want to specify a common ancestortext. These commands read three file or buffer names---variant A,variant B, and the common ancestor. After the comparison is done and the buffers are prepared, theinteractive merging starts. You control the merging by typing special@dfn{merge commands} in the merge buffer. The merge buffer shows you afull merged text, not just differences. For each run of differencesbetween the input texts, you can choose which one of them to keep, oredit them both together. The merge buffer uses a special major mode, Emerge mode, with commandsfor making these choices. But you can also edit the buffer withordinary Emacs commands. At any given time, the attention of Emerge is focused on oneparticular difference, called the @dfn{selected} difference. Thisdifference is marked off in the three buffers like this:@examplevvvvvvvvvvvvvvvvvvvv@var{text that differs}^^^^^^^^^^^^^^^^^^^^@end example@noindentEmerge numbers all the differences sequentially and the modeline always shows the number of the selected difference. Normally, the merge buffer starts out with the A version of the text.But when the A version of a difference agrees with the common ancestor,then the B version is initially preferred for that difference. Emerge leaves the merged text in the merge buffer when you exit. Atthat point, you can save it in a file with @kbd{C-x C-w}. If you give anumeric argument to @code{emerge-files} or@code{emerge-files-with-ancestor}, it reads the name of the output fileusing the minibuffer. (This is the last file name those commands read.)Then exiting from Emerge saves the merged text in the output file. Normally, Emerge commands save the output buffer in its file when youexit. If you abort Emerge with @kbd{C-]}, the Emerge command does notsave the output buffer, but you can save it yourself if you wish.@node Submodes of Emerge@subsection Submodes of Emerge You can choose between two modes for giving merge commands: Fast modeand Edit mode. In Fast mode, basic merge commands are singlecharacters, but ordinary Emacs commands are disabled. This isconvenient if you use only merge commands. In Edit mode, all mergecommands start with the prefix key @kbd{C-c C-c}, and the normal Emacscommands are also available. This allows editing the merge buffer, butslows down Emerge operations. Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch toFast mode. The mode line indicates Edit and Fast modes with @samp{E}and @samp{F}. Emerge has two additional submodes that affect how particular mergecommands work: Auto Advance mode and Skip Prefers mode. If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commandsadvance to the next difference. This lets you go through the mergefaster as long as you simply choose one of the alternatives from theinput. The mode line indicates Auto Advance mode with @samp{A}. If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commandsskip over differences in states prefer-A and prefer-B (@pxref{State ofDifference}). Thus you see only differences for which neither versionis presumed ``correct.'' The mode line indicates Skip Prefers mode with@samp{S}.@findex emerge-auto-advance-mode@findex emerge-skip-prefers-mode Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set orclear Auto Advance mode. Use @kbd{s s}(@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode.These commands turn on the mode with a positive argument, turns it offwith a negative or zero argument, and toggle the mode with no argument.@node State of Difference@subsection State of a Difference In the merge buffer, a difference is marked with lines of @samp{v} and@samp{^} characters. Each difference has one of these seven states:@table @asis@item AThe difference is showing the A version. The @kbd{a} command alwaysproduces this state; the mode line indicates it with @samp{A}.@item BThe difference is showing the B version. The @kbd{b} command alwaysproduces this state; the mode line indicates it with @samp{B}.@item default-A@itemx default-BThe difference is showing the A or the B state by default, because youhaven't made a choice. All differences start in the default-A state(and thus the merge buffer is a copy of the A buffer), except those forwhich one alternative is ``preferred'' (see below).When you select a difference, its state changes from default-A ordefault-B to plain A or B. Thus, the selected difference never hasstate default-A or default-B, and these states are never displayed inthe mode line.The command @kbd{d a} chooses default-A as the default state, and @kbd{db} chooses default-B. This chosen default applies to all differenceswhich you haven't ever selected and for which no alternative is preferred.If you are moving through the merge sequentially, the differences youhaven't selected are those following the selected one. Thus, whilemoving sequentially, you can effectively make the A version the defaultfor some sections of the merge buffer and the B version the default forothers by using @kbd{d a} and @kbd{d b} between sections.@item prefer-A@itemx prefer-BThe difference is showing the A or B state because it is@dfn{preferred}. This means that you haven't made an explicit choice,but one alternative seems likely to be right because the otheralternative agrees with the common ancestor. Thus, where the A bufferagrees with the common ancestor, the B version is preferred, becausechances are it is the one that was actually changed.These two states are displayed in the mode line as @samp{A*} and @samp{B*}.@item combinedThe difference is showing a combination of the A and B states, as aresult of the @kbd{x c} or @kbd{x C} commands.Once a difference is in this state, the @kbd{a} and @kbd{b} commandsdon't do anything to it unless you give them a numeric argument.The mode line displays this state as @samp{comb}.@end table@node Merge Commands@subsection Merge Commands Here are the Merge commands for Fast mode; in Edit mode, precede themwith @kbd{C-c C-c}:@table @kbd@item pSelect the previous difference.@item nSelect the next difference.@item aChoose the A version of this difference.@item bChoose the B version of this difference.@item C-u @var{n} jSelect difference number @var{n}.@item .Select the difference containing point. You can use this command in themerge buffer or in the A or B buffer.@item qQuit---finish the merge.@item C-]Abort---exit merging and do not save the output.@item fGo into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.)@item eGo into Edit mode.@item lRecenter (like @kbd{C-l}) all three windows.@item -Specify part of a prefix numeric argument.@item @var{digit}Also specify part of a prefix numeric argument.@item d aChoose the A version as the default from here down inthe merge buffer.@item d bChoose the B version as the default from here down inthe merge buffer.@item c aCopy the A version of this difference into the kill ring.@item c bCopy the B version of this difference into the kill ring.@item i aInsert the A version of this difference at point.@item i bInsert the B version of this difference at point.@item mPut point and mark around the difference.@item ^Scroll all three windows down (like @kbd{M-v}).@item vScroll all three windows up (like @kbd{C-v}).@item <Scroll all three windows left (like @kbd{C-x <}).@item >Scroll all three windows right (like @kbd{C-x >}).@item |Reset horizontal scroll on all three windows.@item x 1Shrink the merge window to one line. (Use @kbd{C-u l} to restore itto full size.)@item x cCombine the two versions of this difference (@pxref{Combining inEmerge}).@item x fShow the names of the files/buffers Emerge is operating on, in a Helpwindow. (Use @kbd{C-u l} to restore windows.)@item x jJoin this difference with the following one.(@kbd{C-u x j} joins this difference with the previous one.)@item x sSplit this difference into two differences. Before you use thiscommand, position point in each of the three buffers at the place whereyou want to split the difference.@item x tTrim identical lines off the top and bottom of the difference.Such lines occur when the A and B versions areidentical but differ from the ancestor version.@end table@node Exiting Emerge@subsection Exiting Emerge The @kbd{q} command (@code{emerge-quit}) finishes the merge, storingthe results into the output file if you specified one. It restores theA and B buffers to their proper contents, or kills them if they werecreated by Emerge and you haven't changed them. It also disables theEmerge commands in the merge buffer, since executing them later coulddamage the contents of the various buffers. @kbd{C-]} aborts the merge. This means exiting without writing theoutput file. If you didn't specify an output file, then there is noreal difference between aborting and finishing the merge. If the Emerge command was called from another Lisp program, then itsreturn value is @code{t} for successful completion, or @code{nil} if youabort.@node Combining in Emerge@subsection Combining the Two Versions Sometimes you want to keep @emph{both} alternatives for a particulardifference. To do this, use @kbd{x c}, which edits the merge bufferlike this:@example@group#ifdef NEW@var{version from A buffer}#else /* not NEW */@var{version from B buffer}#endif /* not NEW */@end group@end example@noindent@vindex emerge-combine-versions-templateWhile this example shows C preprocessor conditionals delimiting the twoalternative versions, you can specify the strings to use by settingthe variable @code{emerge-combine-versions-template} to a string of yourchoice. In the string, @samp{%a} says where to put version A, and@samp{%b} says where to put version B. The default setting, whichproduces the results shown above, looks like this:@example@group"#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"@end group@end example@node Fine Points of Emerge@subsection Fine Points of Emerge During the merge, you mustn't try to edit the A and B buffers yourself.Emerge modifies them temporarily, but ultimately puts them back the waythey were. You can have any number of merges going at once---just don't use any onebuffer as input to more than one merge at once, since the temporarychanges made in these buffers would get in each other's way. Starting Emerge can take a long time because it needs to compare thefiles fully. Emacs can't do anything else until @code{diff} finishes.Perhaps in the future someone will change Emerge to do the comparison inthe background when the input files are large---then you could keep ondoing other things with Emacs until Emerge is ready to acceptcommands.@vindex emerge-startup-hook After setting up the merge, Emerge runs the hook@code{emerge-startup-hook} (@pxref{Hooks}).