1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985,86,87,93,94,95,97,99,00,2001 Free Software Foundation, Inc.
3 @c See file emacs.texi for copying conditions.
4 @node Maintaining, Abbrevs, Building, Top
5 @chapter Maintaining Programs
8 @cindex program editing
10 This chapter describes Emacs features for maintaining programs. The
11 version control features (@pxref{Version Control}) are also
12 particularly useful for this purpose.
15 * Change Log:: Maintaining a change history for your program.
17 * Authors:: Maintaining the Emacs @file{AUTHORS} file.
19 * Tags:: Go direct to any function in your program in one
20 command. Tags remembers which file it is in.
21 * Emerge:: A convenient way of merging two versions of a program.
29 @findex add-change-log-entry-other-window
30 The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
31 file for the file you are editing
32 (@code{add-change-log-entry-other-window}). If that file is actually
33 a backup file, it makes an entry appropriate for the file's
34 parent---that is useful for making log entries for functions that
35 have been deleted in the current version.
37 A change log file contains a chronological record of when and why you
38 have changed a program, consisting of a sequence of entries describing
39 individual changes. Normally it is kept in a file called
40 @file{ChangeLog} in the same directory as the file you are editing, or
41 one of its parent directories. A single @file{ChangeLog} file can
42 record changes for all the files in its directory and all its
45 You should put a copyright notice and permission notice at the
46 end of the change log file. Here is an example:
49 Copyright 1997, 1998 Free Software Foundation, Inc.
50 Copying and distribution of this file, with or without modification, are
51 permitted provided the copyright notice and this notice are preserved.
55 Of course, you should substitute the proper years and copyright holder.
57 A change log entry starts with a header line that contains the
58 current date, your name, and your email address (taken from the
59 variable @code{user-mail-address}). Aside from these header lines,
60 every line in the change log starts with a space or a tab. The bulk
61 of the entry consists of @dfn{items}, each of which starts with a line
62 starting with whitespace and a star. Here are two entries, both dated
63 in May 1993, each with two items:
69 1993-05-25 Richard Stallman <rms@@gnu.org>
71 * man.el: Rename symbols `man-*' to `Man-*'.
72 (manual-entry): Make prompt string clearer.
74 * simple.el (blink-matching-paren-distance):
75 Change default to 12,000.
77 1993-05-24 Richard Stallman <rms@@gnu.org>
79 * vc.el (minor-mode-map-alist): Don't use it if it's void.
80 (vc-cancel-version): Doc fix.
83 One entry can describe several changes; each change should have its
84 own item. Normally there should be a blank line between items. When
85 items are related (parts of the same change, in different places), group
86 them by leaving no blank line between them. The second entry above
87 contains two items grouped in this way.
89 @kbd{C-x 4 a} visits the change log file and creates a new entry
90 unless the most recent entry is for today's date and your name. It
91 also creates a new item for the current file. For many languages, it
92 can even guess the name of the function or other object that was
95 @vindex add-log-keep-changes-together
96 When the option @code{add-log-keep-changes-together} is
97 non-@code{nil}, @kbd{C-x 4 a} adds to any existing entry for the file
98 rather than starting a new entry.
100 @vindex change-log-version-info-enabled
101 @vindex change-log-version-number-regexp-list
102 @cindex file version in change log entries
103 If the value of the variable @code{change-log-version-info-enabled}
104 is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the
105 change log entry. It finds the version number by searching the first
106 ten percent of the file, using regular expressions from the variable
107 @code{change-log-version-number-regexp-list}.
109 @cindex Change Log mode
110 @findex change-log-mode
111 The change log file is visited in Change Log mode. In this major
112 mode, each bunch of grouped items counts as one paragraph, and each
113 entry is considered a page. This facilitates editing the entries.
114 @kbd{C-j} and auto-fill indent each new line like the previous line;
115 this is convenient for entering the contents of an entry.
117 @findex change-log-merge
118 You can use the command @kbd{M-x change-log-merge} to merge other
119 log files into a buffer in Change Log Mode, preserving the date
122 @findex change-log-redate
123 @cindex converting change log date style
124 Versions of Emacs before 20.1 used a different format for the time of
125 the change log entry:
128 Fri May 25 11:23:23 1993 Richard Stallman <rms@@gnu.org>
132 The @kbd{M-x change-log-redate} command converts all the old-style
133 date entries in the change log file visited in the current buffer to
134 the new format, to make the file uniform in style. This is handy when
135 entries are contributed by many different people, some of whom use old
138 Version control systems are another way to keep track of changes in your
139 program and keep a change log. @xref{Log Buffer}.
142 @c This is commented out because the command is specific
143 @c to maintenance of Emacs itself.
146 @section @file{AUTHORS} files
147 @cindex @file{AUTHORS} file
149 Programs which have many contributors usually include a file named
150 @file{AUTHORS} in their distribution, which lists the individual
151 contributions. Emacs has a special command for maintaining the
152 @file{AUTHORS} file that is part of the Emacs distribution.
155 The @kbd{M-x authors} command prompts for the name of the root of the
156 Emacs source directory. It then scans @file{ChangeLog} files and Lisp
157 source files under that directory for information about authors of
158 individual packages, and people who made changes in source files, and
159 puts the information it gleans into a buffer named @samp{*Authors*}.
160 You can then edit the contents of that buffer and merge it with the
161 existing @file{AUTHORS} file.
163 Do not assume that this command finds all the contributors; don't
164 assume that a person not listed in the output was not a contributor.
165 If you merged in someone's contribution and did not put his name
166 in the change log, he won't show up in @kbd{M-x authors} either.
173 A @dfn{tags table} is a description of how a multi-file program is
174 broken up into files. It lists the names of the component files and the
175 names and positions of the functions (or other named subunits) in each
176 file. Grouping the related files makes it possible to search or replace
177 through all the files with one command. Recording the function names
178 and positions makes possible the @kbd{M-.} command which finds the
179 definition of a function by looking up which of the files it is in.
181 Tags tables are stored in files called @dfn{tags table files}. The
182 conventional name for a tags table file is @file{TAGS}.
184 Each entry in the tags table records the name of one tag, the name of the
185 file that the tag is defined in (implicitly), and the position in that file
186 of the tag's definition.
188 Just what names from the described files are recorded in the tags table
189 depends on the programming language of the described file. They
190 normally include all file names, functions and subroutines, and may
191 also include global variables, data types, and anything else
192 convenient. Each name recorded is called a @dfn{tag}.
194 @cindex C++ class browser, tags
196 @cindex class browser, C++
198 See also the Ebrowse facility, which is tailored for C++.
199 @xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}.
202 * Tag Syntax:: Tag syntax for various types of code and text files.
203 * Create Tags Table:: Creating a tags table with @code{etags}.
204 * Etags Regexps:: Create arbitrary tags using regular expressions.
205 * Select Tags Table:: How to visit a tags table.
206 * Find Tag:: Commands to find the definition of a specific tag.
207 * Tags Search:: Using a tags table for searching and replacing.
208 * List Tags:: Listing and finding tags defined in a file.
212 @subsection Source File Tag Syntax
214 Here is how tag syntax is defined for the most popular languages:
218 In C code, any C function or typedef is a tag, and so are definitions of
219 @code{struct}, @code{union} and @code{enum}.
220 @code{#define} macro definitions and @code{enum} constants are also
221 tags, unless you specify @samp{--no-defines} when making the tags table.
222 Similarly, global variables are tags, unless you specify
223 @samp{--no-globals}. Use of @samp{--no-globals} and @samp{--no-defines}
224 can make the tags table file much smaller.
226 You can tag function declarations and external variables in addition
227 to function definitions by giving the @samp{--declarations} option to
231 In C++ code, in addition to all the tag constructs of C code, member
232 functions are also recognized, and optionally member variables if you
233 use the @samp{--members} option. Tags for variables and functions in
234 classes are named @samp{@var{class}::@var{variable}} and
235 @samp{@var{class}::@var{function}}. @code{operator} definitions have
236 tag names like @samp{operator+}.
239 In Java code, tags include all the constructs recognized in C++, plus
240 the @code{interface}, @code{extends} and @code{implements} constructs.
241 Tags for variables and functions in classes are named
242 @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
245 In La@TeX{} text, the argument of any of the commands @code{\chapter},
246 @code{\section}, @code{\subsection}, @code{\subsubsection},
247 @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
248 @code{\part}, @code{\appendix}, @code{\entry}, or @code{\index}, is a
251 Other commands can make tags as well, if you specify them in the
252 environment variable @env{TEXTAGS} before invoking @code{etags}. The
253 value of this environment variable should be a colon-separated list of
254 command names. For example,
257 TEXTAGS="def:newcommand:newenvironment"
262 specifies (using Bourne shell syntax) that the commands @samp{\def},
263 @samp{\newcommand} and @samp{\newenvironment} also define tags.
266 In Lisp code, any function defined with @code{defun}, any variable
267 defined with @code{defvar} or @code{defconst}, and in general the first
268 argument of any expression that starts with @samp{(def} in column zero, is
272 In Scheme code, tags include anything defined with @code{def} or with a
273 construct whose name starts with @samp{def}. They also include variables
274 set with @code{set!} at top level in the file.
277 Several other languages are also supported:
282 In Ada code, functions, procedures, packages, tasks, and types are
283 tags. Use the @samp{--packages-only} option to create tags for
286 In Ada, the same name can be used for different kinds of entity
287 (e.g.@:, for a procedure and for a function). Also, for things like
288 packages, procedures and functions, there is the spec (i.e.@: the
289 interface) and the body (i.e.@: the implementation). To make it
290 easier to pick the definition you want, Ada tag name have suffixes
291 indicating the type of entity:
308 Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
309 directly to the body of the package @code{bidule}, while @kbd{M-x
310 find-tag @key{RET} bidule @key{RET}} will just search for any tag
314 In assembler code, labels appearing at the beginning of a line,
315 followed by a colon, are tags.
318 In Bison or Yacc input files, each rule defines as a tag the nonterminal
319 it constructs. The portions of the file that contain C code are parsed
323 In Cobol code, tags are paragraph names; that is, any word starting in
324 column 8 and followed by a period.
327 In Erlang code, the tags are the functions, records, and macros defined
331 In Fortran code, functions, subroutines and block data are tags.
334 In makefiles, targets are tags.
337 In Objective C code, tags include Objective C definitions for classes,
338 class categories, methods, and protocols.
341 In Pascal code, the tags are the functions and procedures defined in
345 In Perl code, the tags are the procedures defined by the @code{sub},
346 @code{my} and @code{local} keywords. Use @samp{--globals} if you want
347 to tag global variables.
350 In PostScript code, the tags are the functions.
353 In Prolog code, a tag name appears at the left margin.
356 In Python code, @code{def} or @code{class} at the beginning of a line
360 You can also generate tags based on regexp matching (@pxref{Etags
361 Regexps}) to handle other formats and languages.
363 @node Create Tags Table
364 @subsection Creating Tags Tables
365 @cindex @code{etags} program
367 The @code{etags} program is used to create a tags table file. It knows
368 the syntax of several languages, as described in
370 the previous section.
375 Here is how to run @code{etags}:
378 etags @var{inputfiles}@dots{}
382 The @code{etags} program reads the specified files, and writes a tags
383 table named @file{TAGS} in the current working directory.
385 If the specified files don't exist, @code{etags} looks for
386 compressed versions of them and uncompresses them to read them. Under
387 MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz}
388 if it is given @samp{mycode.c} on the command line and @file{mycode.c}
391 @code{etags} recognizes the language used in an input file based on
392 its file name and contents. You can specify the language with the
393 @samp{--language=@var{name}} option, described below.
395 If the tags table data become outdated due to changes in the files
396 described in the table, the way to update the tags table is the same
397 way it was made in the first place. If the tags table fails to record
398 a tag, or records it for the wrong file, then Emacs cannot possibly
399 find its definition until you update the tags table. However, if the
400 position recorded in the tags table becomes a little bit wrong (due to
401 other editing), the only consequence is a slight delay in finding the
402 tag. Even if the stored position is very far wrong, Emacs will still
403 find the tag, after searching most of the file for it. Even that
404 delay is hardly noticeable with today's computers.
406 So you should update a tags table when you define new tags that you want
407 to have listed, or when you move tag definitions from one file to another,
408 or when changes become substantial. Normally there is no need to update
409 the tags table after each edit, or even every day.
411 One tags table can virtually include another. Specify the included
412 tags file name with the @samp{--include=@var{file}} option when
413 creating the file that is to include it. The latter file then acts as
414 if it covered all the source files specified in the included file, as
415 well as the files it directly contains.
417 If you specify the source files with relative file names when you run
418 @code{etags}, the tags file will contain file names relative to the
419 directory where the tags file was initially written. This way, you can
420 move an entire directory tree containing both the tags file and the
421 source files, and the tags file will still refer correctly to the source
424 If you specify absolute file names as arguments to @code{etags}, then
425 the tags file will contain absolute file names. This way, the tags file
426 will still refer to the same files even if you move it, as long as the
427 source files remain in the same place. Absolute file names start with
428 @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
430 When you want to make a tags table from a great number of files, you
431 may have problems listing them on the command line, because some systems
432 have a limit on its length. The simplest way to circumvent this limit
433 is to tell @code{etags} to read the file names from its standard input,
434 by typing a dash in place of the file names, like this:
437 find . -name "*.[chCH]" -print | etags -
440 Use the option @samp{--language=@var{name}} to specify the language
441 explicitly. You can intermix these options with file names; each one
442 applies to the file names that follow it. Specify
443 @samp{--language=auto} to tell @code{etags} to resume guessing the
444 language from the file names and file contents. Specify
445 @samp{--language=none} to turn off language-specific processing
446 entirely; then @code{etags} recognizes tags by regexp matching alone
447 (@pxref{Etags Regexps}).
449 @samp{etags --help} prints the list of the languages @code{etags}
450 knows, and the file name rules for guessing the language. It also prints
451 a list of all the available @code{etags} options, together with a short
455 @subsection Etags Regexps
457 The @samp{--regex} option provides a general way of recognizing tags
458 based on regexp matching. You can freely intermix it with file names.
459 Each @samp{--regex} option adds to the preceding ones, and applies only
460 to the following files. The syntax is:
463 --regex=/@var{tagregexp}[/@var{nameregexp}]/
467 where @var{tagregexp} is used to match the lines to tag. It is always
468 anchored, that is, it behaves as if preceded by @samp{^}. If you want
469 to account for indentation, just match any initial number of blanks by
470 beginning your regular expression with @samp{[ \t]*}. In the regular
471 expressions, @samp{\} quotes the next character, and @samp{\t} stands
472 for the tab character. Note that @code{etags} does not handle the other
473 C escape sequences for special characters.
475 @cindex interval operator (in regexps)
476 The syntax of regular expressions in @code{etags} is the same as in
477 Emacs, augmented with the @dfn{interval operator}, which works as in
478 @code{grep} and @code{ed}. The syntax of an interval operator is
479 @samp{\@{@var{m},@var{n}\@}}, and its meaning is to match the preceding
480 expression at least @var{m} times and up to @var{n} times.
482 You should not match more characters with @var{tagregexp} than that
483 needed to recognize what you want to tag. If the match is such that
484 more characters than needed are unavoidably matched by @var{tagregexp}
485 (as will usually be the case), you should add a @var{nameregexp}, to
486 pick out just the tag. This will enable Emacs to find tags more
487 accurately and to do completion on tag names more reliably. You can
488 find some examples below.
490 The option @samp{--ignore-case-regex} (or @samp{-c}) works like
491 @samp{--regex}, except that matching ignores case. This is
492 appropriate for certain programming languages.
494 The @samp{-R} option deletes all the regexps defined with
495 @samp{--regex} options. It applies to the file names following it, as
496 you can see from the following example:
499 etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \
500 bar.ber -R --lang=lisp los.er
504 Here @code{etags} chooses the parsing language for @file{voo.doo} and
505 @file{bar.ber} according to their contents. @code{etags} also uses
506 @var{reg1} to recognize additional tags in @file{voo.doo}, and both
507 @var{reg1} and @var{reg2} to recognize additional tags in
508 @file{bar.ber}. @code{etags} uses the Lisp tags rules, and no regexp
509 matching, to recognize tags in @file{los.er}.
511 You can specify a regular expression for a particular language, by
512 writing @samp{@{lang@}} in front of it. Then @code{etags} will use
513 the regular expression only for files of that language. (@samp{etags
514 --help} prints the list of languages recognized by @code{etags}.) The
515 following example tags the @code{DEFVAR} macros in the Emacs source
516 files, for the C language only:
519 --regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
523 This feature is particularly useful when you store a list of regular
524 expressions in a file. The following option syntax instructs
525 @code{etags} to read two files of regular expressions. The regular
526 expressions contained in the second file are matched without regard to
530 --regex=@@first-file --ignore-case-regex=@@second-file
534 A regex file contains one regular expressions per line. Empty lines,
535 and lines beginning with space or tab are ignored. When the first
536 character in a line is @samp{@@}, @code{etags} assumes that the rest
537 of the line is the name of a file of regular expressions; thus, one
538 such file can include another file. All the other lines are taken to
539 be regular expressions. If the first non-whitespace text on the line
540 is @samp{--}, that line is a comment.
542 For example, one can create a file called @samp{emacs.tags} with the
546 -- This is for GNU Emacs C source files
547 @{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
551 and then use it like this:
554 etags --regex=@@emacs.tags *.[ch] */*.[ch]
557 Here are some more examples. The regexps are quoted to protect them
558 from shell interpretation.
566 etags --language=none \
567 --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
568 --regex='/###key \(.*\)/\1/' \
569 --regex='/[ \t]*global[ \t].*/' \
574 Note that tags are not generated for scripts, so that you have to add
575 a line by yourself of the form @samp{###key @var{scriptname}} if you
582 etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
589 etags --language=none \
590 --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
591 --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
592 \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
596 @node Select Tags Table
597 @subsection Selecting a Tags Table
599 @vindex tags-file-name
600 @findex visit-tags-table
601 Emacs has at any time one @dfn{selected} tags table, and all the commands
602 for working with tags tables use the selected one. To select a tags table,
603 type @kbd{M-x visit-tags-table}, which reads the tags table file name as an
604 argument. The name @file{TAGS} in the default directory is used as the
607 All this command does is store the file name in the variable
608 @code{tags-file-name}. Emacs does not actually read in the tags table
609 contents until you try to use them. Setting this variable yourself is just
610 as good as using @code{visit-tags-table}. The variable's initial value is
611 @code{nil}; that value tells all the commands for working with tags tables
612 that they must ask for a tags table file name to use.
614 Using @code{visit-tags-table} when a tags table is already loaded
615 gives you a choice: you can add the new tags table to the current list
616 of tags tables, or start a new list. The tags commands use all the tags
617 tables in the current list. If you start a new list, the new tags table
618 is used @emph{instead} of others. If you add the new table to the
619 current list, it is used @emph{as well as} the others. When the tags
620 commands scan the list of tags tables, they don't always start at the
621 beginning of the list; they start with the first tags table (if any)
622 that describes the current file, proceed from there to the end of the
623 list, and then scan from the beginning of the list until they have
624 covered all the tables in the list.
626 @vindex tags-table-list
627 You can specify a precise list of tags tables by setting the variable
628 @code{tags-table-list} to a list of strings, like this:
630 @c keep this on two lines for formatting in smallbook
633 (setq tags-table-list
634 '("~/emacs" "/usr/local/lib/emacs/src"))
639 This tells the tags commands to look at the @file{TAGS} files in your
640 @file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
641 directory. The order depends on which file you are in and which tags
642 table mentions that file, as explained above.
644 Do not set both @code{tags-file-name} and @code{tags-table-list}.
647 @subsection Finding a Tag
649 The most important thing that a tags table enables you to do is to find
650 the definition of a specific tag.
653 @item M-.@: @var{tag} @key{RET}
654 Find first definition of @var{tag} (@code{find-tag}).
656 Find next alternate definition of last tag specified.
658 Go back to previous tag found.
659 @item C-M-. @var{pattern} @key{RET}
660 Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
662 Find the next tag whose name matches the last pattern used.
663 @item C-x 4 .@: @var{tag} @key{RET}
664 Find first definition of @var{tag}, but display it in another window
665 (@code{find-tag-other-window}).
666 @item C-x 5 .@: @var{tag} @key{RET}
667 Find first definition of @var{tag}, and create a new frame to select the
668 buffer (@code{find-tag-other-frame}).
670 Pop back to where you previously invoked @kbd{M-.} and friends.
675 @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
676 a specified tag. It searches through the tags table for that tag, as a
677 string, and then uses the tags table info to determine the file that the
678 definition is in and the approximate character position in the file of
679 the definition. Then @code{find-tag} visits that file, moves point to
680 the approximate character position, and searches ever-increasing
681 distances away to find the tag definition.
683 If an empty argument is given (just type @key{RET}), the balanced
684 expression in the buffer before or around point is used as the
685 @var{tag} argument. @xref{Expressions}.
687 You don't need to give @kbd{M-.} the full name of the tag; a part
688 will do. This is because @kbd{M-.} finds tags in the table which
689 contain @var{tag} as a substring. However, it prefers an exact match
690 to a substring match. To find other tags that match the same
691 substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
692 M-.}; this does not read a tag name, but continues searching the tags
693 table's text for another tag containing the same substring last used.
694 If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier
695 alternative to @kbd{C-u M-.}.
698 @findex find-tag-other-window
700 @findex find-tag-other-frame
701 Like most commands that can switch buffers, @code{find-tag} has a
702 variant that displays the new buffer in another window, and one that
703 makes a new frame for it. The former is @kbd{C-x 4 .}, which invokes
704 the command @code{find-tag-other-window}. The latter is @kbd{C-x 5 .},
705 which invokes @code{find-tag-other-frame}.
707 To move back to places you've found tags recently, use @kbd{C-u -
708 M-.}; more generally, @kbd{M-.} with a negative numeric argument. This
709 command can take you to another buffer. @kbd{C-x 4 .} with a negative
710 argument finds the previous tag location in another window.
714 @vindex find-tag-marker-ring-length
715 As well as going back to places you've found tags recently, you can go
716 back to places @emph{from where} you found them. Use @kbd{M-*}, which
717 invokes the command @code{pop-tag-mark}, for this. Typically you would
718 find and study the definition of something with @kbd{M-.} and then
719 return to where you were with @kbd{M-*}.
721 Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
722 a depth determined by the variable @code{find-tag-marker-ring-length}.
724 @findex find-tag-regexp
726 The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
727 match a specified regular expression. It is just like @kbd{M-.} except
728 that it does regexp matching instead of substring matching.
731 @subsection Searching and Replacing with Tags Tables
732 @cindex search and replace in multiple files
733 @cindex multiple-file search and replace
735 The commands in this section visit and search all the files listed in the
736 selected tags table, one by one. For these commands, the tags table serves
737 only to specify a sequence of files to search.
740 @item M-x tags-search @key{RET} @var{regexp} @key{RET}
741 Search for @var{regexp} through the files in the selected tags
743 @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
744 Perform a @code{query-replace-regexp} on each file in the selected tags table.
746 Restart one of the commands above, from the current location of point
747 (@code{tags-loop-continue}).
751 @kbd{M-x tags-search} reads a regexp using the minibuffer, then
752 searches for matches in all the files in the selected tags table, one
753 file at a time. It displays the name of the file being searched so you
754 can follow its progress. As soon as it finds an occurrence,
755 @code{tags-search} returns.
758 @findex tags-loop-continue
759 Having found one match, you probably want to find all the rest. To find
760 one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
761 @code{tags-search}. This searches the rest of the current buffer, followed
762 by the remaining files of the tags table.@refill
764 @findex tags-query-replace
765 @kbd{M-x tags-query-replace} performs a single
766 @code{query-replace-regexp} through all the files in the tags table. It
767 reads a regexp to search for and a string to replace with, just like
768 ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
769 tags-search}, but repeatedly, processing matches according to your
770 input. @xref{Replace}, for more information on query replace.
772 @vindex tags-case-fold-search
773 @cindex case-sensitivity and tags search
774 You can control the case-sensitivity of tags search commands by
775 customizing the value of the variable @code{tags-case-fold-search}. The
776 default is to use the same setting as the value of
777 @code{case-fold-search} (@pxref{Search Case}).
779 It is possible to get through all the files in the tags table with a
780 single invocation of @kbd{M-x tags-query-replace}. But often it is
781 useful to exit temporarily, which you can do with any input event that
782 has no special query replace meaning. You can resume the query replace
783 subsequently by typing @kbd{M-,}; this command resumes the last tags
784 search or replace command that you did.
786 The commands in this section carry out much broader searches than the
787 @code{find-tag} family. The @code{find-tag} commands search only for
788 definitions of tags that match your substring or regexp. The commands
789 @code{tags-search} and @code{tags-query-replace} find every occurrence
790 of the regexp, as ordinary search commands and replace commands do in
793 These commands create buffers only temporarily for the files that they
794 have to search (those which are not already visited in Emacs buffers).
795 Buffers in which no match is found are quickly killed; the others
798 It may have struck you that @code{tags-search} is a lot like
799 @code{grep}. You can also run @code{grep} itself as an inferior of
800 Emacs and have Emacs show you the matching lines one by one. This works
801 much like running a compilation; finding the source locations of the
802 @code{grep} matches works like finding the compilation errors.
806 @subsection Tags Table Inquiries
809 @item M-x list-tags @key{RET} @var{file} @key{RET}
810 Display a list of the tags defined in the program file @var{file}.
811 @item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
812 Display a list of all tags matching @var{regexp}.
816 @kbd{M-x list-tags} reads the name of one of the files described by
817 the selected tags table, and displays a list of all the tags defined in
818 that file. The ``file name'' argument is really just a string to
819 compare against the file names recorded in the tags table; it is read as
820 a string rather than as a file name. Therefore, completion and
821 defaulting are not available, and you must enter the file name the same
822 way it appears in the tags table. Do not include a directory as part of
823 the file name unless the file name recorded in the tags table includes a
827 @vindex tags-apropos-verbose
828 @kbd{M-x tags-apropos} is like @code{apropos} for tags
829 (@pxref{Apropos}). It finds all the tags in the selected tags table
830 whose entries match @var{regexp}, and displays them. If the variable
831 @code{tags-apropos-verbose} is non-@code{nil}, it displays the names
832 of the tags files together with the tag names.
834 @vindex tags-tag-face
835 @vindex tags-apropos-additional-actions
836 You can customize the appearance of the output with the face
837 @code{tags-tag-face}. You can display additional output with @kbd{M-x
838 tags-apropos} by customizing the variable
839 @code{tags-apropos-additional-actions}---see its documentation for
842 You can also use the collection of tag names to complete a symbol
843 name in the buffer. @xref{Symbol Completion}.
846 @section Merging Files with Emerge
848 @cindex merging files
850 It's not unusual for programmers to get their signals crossed and modify
851 the same program in two different directions. To recover from this
852 confusion, you need to merge the two versions. Emerge makes this
853 easier. See also @ref{Comparing Files}, for commands to compare
854 in a more manual fashion, and @ref{Top, Ediff,, ediff, The Ediff Manual}.
857 * Overview of Emerge:: How to start Emerge. Basic concepts.
858 * Submodes of Emerge:: Fast mode vs. Edit mode.
859 Skip Prefers mode and Auto Advance mode.
860 * State of Difference:: You do the merge by specifying state A or B
862 * Merge Commands:: Commands for selecting a difference,
863 changing states of differences, etc.
864 * Exiting Emerge:: What to do when you've finished the merge.
865 * Combining in Emerge:: How to keep both alternatives for a difference.
866 * Fine Points of Emerge:: Misc.
869 @node Overview of Emerge
870 @subsection Overview of Emerge
872 To start Emerge, run one of these four commands:
875 @item M-x emerge-files
877 Merge two specified files.
879 @item M-x emerge-files-with-ancestor
880 @findex emerge-files-with-ancestor
881 Merge two specified files, with reference to a common ancestor.
883 @item M-x emerge-buffers
884 @findex emerge-buffers
887 @item M-x emerge-buffers-with-ancestor
888 @findex emerge-buffers-with-ancestor
889 Merge two buffers with reference to a common ancestor in a third
893 @cindex merge buffer (Emerge)
894 @cindex A and B buffers (Emerge)
895 The Emerge commands compare two files or buffers, and display the
896 comparison in three buffers: one for each input text (the @dfn{A buffer}
897 and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging
898 takes place. The merge buffer shows the full merged text, not just the
899 differences. Wherever the two input texts differ, you can choose which
900 one of them to include in the merge buffer.
902 The Emerge commands that take input from existing buffers use only the
903 accessible portions of those buffers, if they are narrowed
906 If a common ancestor version is available, from which the two texts to
907 be merged were both derived, Emerge can use it to guess which
908 alternative is right. Wherever one current version agrees with the
909 ancestor, Emerge presumes that the other current version is a deliberate
910 change which should be kept in the merged version. Use the
911 @samp{with-ancestor} commands if you want to specify a common ancestor
912 text. These commands read three file or buffer names---variant A,
913 variant B, and the common ancestor.
915 After the comparison is done and the buffers are prepared, the
916 interactive merging starts. You control the merging by typing special
917 @dfn{merge commands} in the merge buffer. The merge buffer shows you a
918 full merged text, not just differences. For each run of differences
919 between the input texts, you can choose which one of them to keep, or
920 edit them both together.
922 The merge buffer uses a special major mode, Emerge mode, with commands
923 for making these choices. But you can also edit the buffer with
924 ordinary Emacs commands.
926 At any given time, the attention of Emerge is focused on one
927 particular difference, called the @dfn{selected} difference. This
928 difference is marked off in the three buffers like this:
932 @var{text that differs}
937 Emerge numbers all the differences sequentially and the mode
938 line always shows the number of the selected difference.
940 Normally, the merge buffer starts out with the A version of the text.
941 But when the A version of a difference agrees with the common ancestor,
942 then the B version is initially preferred for that difference.
944 Emerge leaves the merged text in the merge buffer when you exit. At
945 that point, you can save it in a file with @kbd{C-x C-w}. If you give a
946 numeric argument to @code{emerge-files} or
947 @code{emerge-files-with-ancestor}, it reads the name of the output file
948 using the minibuffer. (This is the last file name those commands read.)
949 Then exiting from Emerge saves the merged text in the output file.
951 Normally, Emerge commands save the output buffer in its file when you
952 exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not
953 save the output buffer, but you can save it yourself if you wish.
955 @node Submodes of Emerge
956 @subsection Submodes of Emerge
958 You can choose between two modes for giving merge commands: Fast mode
959 and Edit mode. In Fast mode, basic merge commands are single
960 characters, but ordinary Emacs commands are disabled. This is
961 convenient if you use only merge commands. In Edit mode, all merge
962 commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs
963 commands are also available. This allows editing the merge buffer, but
964 slows down Emerge operations.
966 Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to
967 Fast mode. The mode line indicates Edit and Fast modes with @samp{E}
970 Emerge has two additional submodes that affect how particular merge
971 commands work: Auto Advance mode and Skip Prefers mode.
973 If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands
974 advance to the next difference. This lets you go through the merge
975 faster as long as you simply choose one of the alternatives from the
976 input. The mode line indicates Auto Advance mode with @samp{A}.
978 If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands
979 skip over differences in states prefer-A and prefer-B (@pxref{State of
980 Difference}). Thus you see only differences for which neither version
981 is presumed ``correct.'' The mode line indicates Skip Prefers mode with
984 @findex emerge-auto-advance-mode
985 @findex emerge-skip-prefers-mode
986 Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or
987 clear Auto Advance mode. Use @kbd{s s}
988 (@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode.
989 These commands turn on the mode with a positive argument, turns it off
990 with a negative or zero argument, and toggle the mode with no argument.
992 @node State of Difference
993 @subsection State of a Difference
995 In the merge buffer, a difference is marked with lines of @samp{v} and
996 @samp{^} characters. Each difference has one of these seven states:
1000 The difference is showing the A version. The @kbd{a} command always
1001 produces this state; the mode line indicates it with @samp{A}.
1004 The difference is showing the B version. The @kbd{b} command always
1005 produces this state; the mode line indicates it with @samp{B}.
1009 The difference is showing the A or the B state by default, because you
1010 haven't made a choice. All differences start in the default-A state
1011 (and thus the merge buffer is a copy of the A buffer), except those for
1012 which one alternative is ``preferred'' (see below).
1014 When you select a difference, its state changes from default-A or
1015 default-B to plain A or B. Thus, the selected difference never has
1016 state default-A or default-B, and these states are never displayed in
1019 The command @kbd{d a} chooses default-A as the default state, and @kbd{d
1020 b} chooses default-B. This chosen default applies to all differences
1021 which you haven't ever selected and for which no alternative is preferred.
1022 If you are moving through the merge sequentially, the differences you
1023 haven't selected are those following the selected one. Thus, while
1024 moving sequentially, you can effectively make the A version the default
1025 for some sections of the merge buffer and the B version the default for
1026 others by using @kbd{d a} and @kbd{d b} between sections.
1030 The difference is showing the A or B state because it is
1031 @dfn{preferred}. This means that you haven't made an explicit choice,
1032 but one alternative seems likely to be right because the other
1033 alternative agrees with the common ancestor. Thus, where the A buffer
1034 agrees with the common ancestor, the B version is preferred, because
1035 chances are it is the one that was actually changed.
1037 These two states are displayed in the mode line as @samp{A*} and @samp{B*}.
1040 The difference is showing a combination of the A and B states, as a
1041 result of the @kbd{x c} or @kbd{x C} commands.
1043 Once a difference is in this state, the @kbd{a} and @kbd{b} commands
1044 don't do anything to it unless you give them a numeric argument.
1046 The mode line displays this state as @samp{comb}.
1049 @node Merge Commands
1050 @subsection Merge Commands
1052 Here are the Merge commands for Fast mode; in Edit mode, precede them
1057 Select the previous difference.
1060 Select the next difference.
1063 Choose the A version of this difference.
1066 Choose the B version of this difference.
1069 Select difference number @var{n}.
1072 Select the difference containing point. You can use this command in the
1073 merge buffer or in the A or B buffer.
1076 Quit---finish the merge.
1079 Abort---exit merging and do not save the output.
1082 Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.)
1088 Recenter (like @kbd{C-l}) all three windows.
1091 Specify part of a prefix numeric argument.
1094 Also specify part of a prefix numeric argument.
1097 Choose the A version as the default from here down in
1101 Choose the B version as the default from here down in
1105 Copy the A version of this difference into the kill ring.
1108 Copy the B version of this difference into the kill ring.
1111 Insert the A version of this difference at point.
1114 Insert the B version of this difference at point.
1117 Put point and mark around the difference.
1120 Scroll all three windows down (like @kbd{M-v}).
1123 Scroll all three windows up (like @kbd{C-v}).
1126 Scroll all three windows left (like @kbd{C-x <}).
1129 Scroll all three windows right (like @kbd{C-x >}).
1132 Reset horizontal scroll on all three windows.
1135 Shrink the merge window to one line. (Use @kbd{C-u l} to restore it
1139 Combine the two versions of this difference (@pxref{Combining in
1143 Show the names of the files/buffers Emerge is operating on, in a Help
1144 window. (Use @kbd{C-u l} to restore windows.)
1147 Join this difference with the following one.
1148 (@kbd{C-u x j} joins this difference with the previous one.)
1151 Split this difference into two differences. Before you use this
1152 command, position point in each of the three buffers at the place where
1153 you want to split the difference.
1156 Trim identical lines off the top and bottom of the difference.
1157 Such lines occur when the A and B versions are
1158 identical but differ from the ancestor version.
1161 @node Exiting Emerge
1162 @subsection Exiting Emerge
1164 The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing
1165 the results into the output file if you specified one. It restores the
1166 A and B buffers to their proper contents, or kills them if they were
1167 created by Emerge and you haven't changed them. It also disables the
1168 Emerge commands in the merge buffer, since executing them later could
1169 damage the contents of the various buffers.
1171 @kbd{C-]} aborts the merge. This means exiting without writing the
1172 output file. If you didn't specify an output file, then there is no
1173 real difference between aborting and finishing the merge.
1175 If the Emerge command was called from another Lisp program, then its
1176 return value is @code{t} for successful completion, or @code{nil} if you
1179 @node Combining in Emerge
1180 @subsection Combining the Two Versions
1182 Sometimes you want to keep @emph{both} alternatives for a particular
1183 difference. To do this, use @kbd{x c}, which edits the merge buffer
1189 @var{version from A buffer}
1191 @var{version from B buffer}
1192 #endif /* not NEW */
1197 @vindex emerge-combine-versions-template
1198 While this example shows C preprocessor conditionals delimiting the two
1199 alternative versions, you can specify the strings to use by setting
1200 the variable @code{emerge-combine-versions-template} to a string of your
1201 choice. In the string, @samp{%a} says where to put version A, and
1202 @samp{%b} says where to put version B. The default setting, which
1203 produces the results shown above, looks like this:
1207 "#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"
1211 @node Fine Points of Emerge
1212 @subsection Fine Points of Emerge
1214 During the merge, you mustn't try to edit the A and B buffers yourself.
1215 Emerge modifies them temporarily, but ultimately puts them back the way
1218 You can have any number of merges going at once---just don't use any one
1219 buffer as input to more than one merge at once, since the temporary
1220 changes made in these buffers would get in each other's way.
1222 Starting Emerge can take a long time because it needs to compare the
1223 files fully. Emacs can't do anything else until @code{diff} finishes.
1224 Perhaps in the future someone will change Emerge to do the comparison in
1225 the background when the input files are large---then you could keep on
1226 doing other things with Emacs until Emerge is ready to accept
1229 @vindex emerge-startup-hook
1230 After setting up the merge, Emerge runs the hook
1231 @code{emerge-startup-hook} (@pxref{Hooks}).