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.
16 * Tags:: Go direct to any function in your program in one
17 command. Tags remembers which file it is in.
18 * Emerge:: A convenient way of merging two versions of a program.
26 @findex add-change-log-entry-other-window
27 The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
28 file for the file you are editing
29 (@code{add-change-log-entry-other-window}). If that file is actually
30 a backup file, it makes an entry appropriate for the file's
31 parent---that is useful for making log entries for functions that
32 have been deleted in the current version.
34 A change log file contains a chronological record of when and why you
35 have changed a program, consisting of a sequence of entries describing
36 individual changes. Normally it is kept in a file called
37 @file{ChangeLog} in the same directory as the file you are editing, or
38 one of its parent directories. A single @file{ChangeLog} file can
39 record changes for all the files in its directory and all its
42 You should put a copyright notice and permission notice at the
43 end of the change log file. Here is an example:
46 Copyright 1997, 1998 Free Software Foundation, Inc.
47 Copying and distribution of this file, with or without modification, are
48 permitted provided the copyright notice and this notice are preserved.
52 Of course, you should substitute the proper years and copyright holder.
54 A change log entry starts with a header line that contains the
55 current date, your name, and your email address (taken from the
56 variable @code{user-mail-address}). Aside from these header lines,
57 every line in the change log starts with a space or a tab. The bulk
58 of the entry consists of @dfn{items}, each of which starts with a line
59 starting with whitespace and a star. Here are two entries, both dated
60 in May 1993, each with two items:
66 1993-05-25 Richard Stallman <rms@@gnu.org>
68 * man.el: Rename symbols `man-*' to `Man-*'.
69 (manual-entry): Make prompt string clearer.
71 * simple.el (blink-matching-paren-distance):
72 Change default to 12,000.
74 1993-05-24 Richard Stallman <rms@@gnu.org>
76 * vc.el (minor-mode-map-alist): Don't use it if it's void.
77 (vc-cancel-version): Doc fix.
80 One entry can describe several changes; each change should have its
81 own item. Normally there should be a blank line between items. When
82 items are related (parts of the same change, in different places), group
83 them by leaving no blank line between them. The second entry above
84 contains two items grouped in this way.
86 @kbd{C-x 4 a} visits the change log file and creates a new entry
87 unless the most recent entry is for today's date and your name. It
88 also creates a new item for the current file. For many languages, it
89 can even guess the name of the function or other object that was
92 @vindex add-log-keep-changes-together
93 When the option @code{add-log-keep-changes-together} is
94 non-@code{nil}, @kbd{C-x 4 a} adds to any existing entry for the file
95 rather than starting a new entry.
97 @vindex change-log-version-info-enabled
98 @vindex change-log-version-number-regexp-list
99 @cindex file version in change log entries
100 If the value of the variable @code{change-log-version-info-enabled}
101 is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the
102 change log entry. It finds the version number by searching the first
103 ten percent of the file, using regular expressions from the variable
104 @code{change-log-version-number-regexp-list}.
106 @cindex Change Log mode
107 @findex change-log-mode
108 The change log file is visited in Change Log mode. In this major
109 mode, each bunch of grouped items counts as one paragraph, and each
110 entry is considered a page. This facilitates editing the entries.
111 @kbd{C-j} and auto-fill indent each new line like the previous line;
112 this is convenient for entering the contents of an entry.
114 @findex change-log-merge
115 You can use the command @kbd{M-x change-log-merge} to merge other
116 log files into a buffer in Change Log Mode, preserving the date
119 @findex change-log-redate
120 @cindex converting change log date style
121 Versions of Emacs before 20.1 used a different format for the time of
122 the change log entry:
125 Fri May 25 11:23:23 1993 Richard Stallman <rms@@gnu.org>
129 The @kbd{M-x change-log-redate} command converts all the old-style
130 date entries in the change log file visited in the current buffer to
131 the new format, to make the file uniform in style. This is handy when
132 entries are contributed by many different people, some of whom use old
135 Version control systems are another way to keep track of changes in your
136 program and keep a change log. @xref{Log Buffer}.
139 @c This is commented out because the command is specific
140 @c to maintenance of Emacs itself.
143 @section @file{AUTHORS} files
144 @cindex @file{AUTHORS} file
146 Programs which have many contributors usually include a file named
147 @file{AUTHORS} in their distribution, which lists the individual
148 contributions. Emacs has a special command for maintaining the
149 @file{AUTHORS} file that is part of the Emacs distribution.
152 The @kbd{M-x authors} command prompts for the name of the root of the
153 Emacs source directory. It then scans @file{ChangeLog} files and Lisp
154 source files under that directory for information about authors of
155 individual packages, and people who made changes in source files, and
156 puts the information it gleans into a buffer named @samp{*Authors*}.
157 You can then edit the contents of that buffer and merge it with the
158 existing @file{AUTHORS} file.
160 Do not assume that this command finds all the contributors; don't
161 assume that a person not listed in the output was not a contributor.
162 If you merged in someone's contribution and did not put his name
163 in the change log, he won't show up in @kbd{M-x authors} either.
170 A @dfn{tags table} is a description of how a multi-file program is
171 broken up into files. It lists the names of the component files and the
172 names and positions of the functions (or other named subunits) in each
173 file. Grouping the related files makes it possible to search or replace
174 through all the files with one command. Recording the function names
175 and positions makes possible the @kbd{M-.} command which finds the
176 definition of a function by looking up which of the files it is in.
178 Tags tables are stored in files called @dfn{tags table files}. The
179 conventional name for a tags table file is @file{TAGS}.
181 Each entry in the tags table records the name of one tag, the name of the
182 file that the tag is defined in (implicitly), and the position in that file
183 of the tag's definition.
185 Just what names from the described files are recorded in the tags table
186 depends on the programming language of the described file. They
187 normally include all file names, functions and subroutines, and may
188 also include global variables, data types, and anything else
189 convenient. Each name recorded is called a @dfn{tag}.
191 @cindex C++ class browser, tags
193 @cindex class browser, C++
195 See also the Ebrowse facility, which is tailored for C++.
196 @xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}.
199 * Tag Syntax:: Tag syntax for various types of code and text files.
200 * Create Tags Table:: Creating a tags table with @code{etags}.
201 * Etags Regexps:: Create arbitrary tags using regular expressions.
202 * Select Tags Table:: How to visit a tags table.
203 * Find Tag:: Commands to find the definition of a specific tag.
204 * Tags Search:: Using a tags table for searching and replacing.
205 * List Tags:: Listing and finding tags defined in a file.
209 @subsection Source File Tag Syntax
211 Here is how tag syntax is defined for the most popular languages:
215 In C code, any C function or typedef is a tag, and so are definitions of
216 @code{struct}, @code{union} and @code{enum}.
217 @code{#define} macro definitions and @code{enum} constants are also
218 tags, unless you specify @samp{--no-defines} when making the tags table.
219 Similarly, global variables are tags, unless you specify
220 @samp{--no-globals}. Use of @samp{--no-globals} and @samp{--no-defines}
221 can make the tags table file much smaller.
223 You can tag function declarations and external variables in addition
224 to function definitions by giving the @samp{--declarations} option to
228 In C++ code, in addition to all the tag constructs of C code, member
229 functions are also recognized, and optionally member variables if you
230 use the @samp{--members} option. Tags for variables and functions in
231 classes are named @samp{@var{class}::@var{variable}} and
232 @samp{@var{class}::@var{function}}. @code{operator} definitions have
233 tag names like @samp{operator+}.
236 In Java code, tags include all the constructs recognized in C++, plus
237 the @code{interface}, @code{extends} and @code{implements} constructs.
238 Tags for variables and functions in classes are named
239 @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
242 In La@TeX{} text, the argument of any of the commands @code{\chapter},
243 @code{\section}, @code{\subsection}, @code{\subsubsection},
244 @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem},
245 @code{\part}, @code{\appendix}, @code{\entry}, or @code{\index}, is a
248 Other commands can make tags as well, if you specify them in the
249 environment variable @env{TEXTAGS} before invoking @code{etags}. The
250 value of this environment variable should be a colon-separated list of
251 command names. For example,
254 TEXTAGS="def:newcommand:newenvironment"
259 specifies (using Bourne shell syntax) that the commands @samp{\def},
260 @samp{\newcommand} and @samp{\newenvironment} also define tags.
263 In Lisp code, any function defined with @code{defun}, any variable
264 defined with @code{defvar} or @code{defconst}, and in general the first
265 argument of any expression that starts with @samp{(def} in column zero, is
269 In Scheme code, tags include anything defined with @code{def} or with a
270 construct whose name starts with @samp{def}. They also include variables
271 set with @code{set!} at top level in the file.
274 Several other languages are also supported:
279 In Ada code, functions, procedures, packages, tasks, and types are
280 tags. Use the @samp{--packages-only} option to create tags for
283 In Ada, the same name can be used for different kinds of entity
284 (e.g.@:, for a procedure and for a function). Also, for things like
285 packages, procedures and functions, there is the spec (i.e.@: the
286 interface) and the body (i.e.@: the implementation). To make it
287 easier to pick the definition you want, Ada tag name have suffixes
288 indicating the type of entity:
305 Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
306 directly to the body of the package @code{bidule}, while @kbd{M-x
307 find-tag @key{RET} bidule @key{RET}} will just search for any tag
311 In assembler code, labels appearing at the beginning of a line,
312 followed by a colon, are tags.
315 In Bison or Yacc input files, each rule defines as a tag the nonterminal
316 it constructs. The portions of the file that contain C code are parsed
320 In Cobol code, tags are paragraph names; that is, any word starting in
321 column 8 and followed by a period.
324 In Erlang code, the tags are the functions, records, and macros defined
328 In Fortran code, functions, subroutines and block data are tags.
331 In makefiles, targets are tags.
334 In Objective C code, tags include Objective C definitions for classes,
335 class categories, methods, and protocols.
338 In Pascal code, the tags are the functions and procedures defined in
342 In Perl code, the tags are the procedures defined by the @code{sub},
343 @code{my} and @code{local} keywords. Use @samp{--globals} if you want
344 to tag global variables.
347 In PHP code, tags are functions, classes and defines. When using the
348 @samp{--members} option, vars are tags too.
351 In PostScript code, the tags are the functions.
354 In Prolog code, tags are predicates and rules at the beginning of
358 In Python code, @code{def} or @code{class} at the beginning of a line
362 You can also generate tags based on regexp matching (@pxref{Etags
363 Regexps}) to handle other formats and languages.
365 @node Create Tags Table
366 @subsection Creating Tags Tables
367 @cindex @code{etags} program
369 The @code{etags} program is used to create a tags table file. It knows
370 the syntax of several languages, as described in
372 the previous section.
377 Here is how to run @code{etags}:
380 etags @var{inputfiles}@dots{}
384 The @code{etags} program reads the specified files, and writes a tags
385 table named @file{TAGS} in the current working directory.
387 If the specified files don't exist, @code{etags} looks for
388 compressed versions of them and uncompresses them to read them. Under
389 MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz}
390 if it is given @samp{mycode.c} on the command line and @file{mycode.c}
393 @code{etags} recognizes the language used in an input file based on
394 its file name and contents. You can specify the language with the
395 @samp{--language=@var{name}} option, described below.
397 If the tags table data become outdated due to changes in the files
398 described in the table, the way to update the tags table is the same
399 way it was made in the first place. If the tags table fails to record
400 a tag, or records it for the wrong file, then Emacs cannot possibly
401 find its definition until you update the tags table. However, if the
402 position recorded in the tags table becomes a little bit wrong (due to
403 other editing), the only consequence is a slight delay in finding the
404 tag. Even if the stored position is very far wrong, Emacs will still
405 find the tag, after searching most of the file for it. Even that
406 delay is hardly noticeable with today's computers.
408 So you should update a tags table when you define new tags that you want
409 to have listed, or when you move tag definitions from one file to another,
410 or when changes become substantial. Normally there is no need to update
411 the tags table after each edit, or even every day.
413 One tags table can virtually include another. Specify the included
414 tags file name with the @samp{--include=@var{file}} option when
415 creating the file that is to include it. The latter file then acts as
416 if it covered all the source files specified in the included file, as
417 well as the files it directly contains.
419 If you specify the source files with relative file names when you run
420 @code{etags}, the tags file will contain file names relative to the
421 directory where the tags file was initially written. This way, you can
422 move an entire directory tree containing both the tags file and the
423 source files, and the tags file will still refer correctly to the source
426 If you specify absolute file names as arguments to @code{etags}, then
427 the tags file will contain absolute file names. This way, the tags file
428 will still refer to the same files even if you move it, as long as the
429 source files remain in the same place. Absolute file names start with
430 @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
432 When you want to make a tags table from a great number of files, you
433 may have problems listing them on the command line, because some systems
434 have a limit on its length. The simplest way to circumvent this limit
435 is to tell @code{etags} to read the file names from its standard input,
436 by typing a dash in place of the file names, like this:
439 find . -name "*.[chCH]" -print | etags -
442 Use the option @samp{--language=@var{name}} to specify the language
443 explicitly. You can intermix these options with file names; each one
444 applies to the file names that follow it. Specify
445 @samp{--language=auto} to tell @code{etags} to resume guessing the
446 language from the file names and file contents. Specify
447 @samp{--language=none} to turn off language-specific processing
448 entirely; then @code{etags} recognizes tags by regexp matching alone
449 (@pxref{Etags Regexps}).
451 @samp{etags --help} prints the list of the languages @code{etags}
452 knows, and the file name rules for guessing the language. It also prints
453 a list of all the available @code{etags} options, together with a short
457 @subsection Etags Regexps
459 The @samp{--regex} option provides a general way of recognizing tags
460 based on regexp matching. You can freely intermix it with file names.
461 Each @samp{--regex} option adds to the preceding ones, and applies only
462 to the following files. The syntax is:
465 --regex=/@var{tagregexp}[/@var{nameregexp}]/
469 where @var{tagregexp} is used to match the lines to tag. It is always
470 anchored, that is, it behaves as if preceded by @samp{^}. If you want
471 to account for indentation, just match any initial number of blanks by
472 beginning your regular expression with @samp{[ \t]*}. In the regular
473 expressions, @samp{\} quotes the next character, and @samp{\t} stands
474 for the tab character. Note that @code{etags} does not handle the other
475 C escape sequences for special characters.
477 @cindex interval operator (in regexps)
478 The syntax of regular expressions in @code{etags} is the same as in
479 Emacs, augmented with the @dfn{interval operator}, which works as in
480 @code{grep} and @code{ed}. The syntax of an interval operator is
481 @samp{\@{@var{m},@var{n}\@}}, and its meaning is to match the preceding
482 expression at least @var{m} times and up to @var{n} times.
484 You should not match more characters with @var{tagregexp} than that
485 needed to recognize what you want to tag. If the match is such that
486 more characters than needed are unavoidably matched by @var{tagregexp}
487 (as will usually be the case), you should add a @var{nameregexp}, to
488 pick out just the tag. This will enable Emacs to find tags more
489 accurately and to do completion on tag names more reliably. You can
490 find some examples below.
492 The option @samp{--ignore-case-regex} (or @samp{-c}) works like
493 @samp{--regex}, except that matching ignores case. This is
494 appropriate for certain programming languages.
496 The @samp{-R} option deletes all the regexps defined with
497 @samp{--regex} options. It applies to the file names following it, as
498 you can see from the following example:
501 etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \
502 bar.ber -R --lang=lisp los.er
506 Here @code{etags} chooses the parsing language for @file{voo.doo} and
507 @file{bar.ber} according to their contents. @code{etags} also uses
508 @var{reg1} to recognize additional tags in @file{voo.doo}, and both
509 @var{reg1} and @var{reg2} to recognize additional tags in
510 @file{bar.ber}. @code{etags} uses the Lisp tags rules, and no regexp
511 matching, to recognize tags in @file{los.er}.
513 You can specify a regular expression for a particular language, by
514 writing @samp{@{lang@}} in front of it. Then @code{etags} will use
515 the regular expression only for files of that language. (@samp{etags
516 --help} prints the list of languages recognized by @code{etags}.) The
517 following example tags the @code{DEFVAR} macros in the Emacs source
518 files, for the C language only:
521 --regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
525 This feature is particularly useful when you store a list of regular
526 expressions in a file. The following option syntax instructs
527 @code{etags} to read two files of regular expressions. The regular
528 expressions contained in the second file are matched without regard to
532 --regex=@@first-file --ignore-case-regex=@@second-file
536 A regex file contains one regular expressions per line. Empty lines,
537 and lines beginning with space or tab are ignored. When the first
538 character in a line is @samp{@@}, @code{etags} assumes that the rest
539 of the line is the name of a file of regular expressions; thus, one
540 such file can include another file. All the other lines are taken to
541 be regular expressions. If the first non-whitespace text on the line
542 is @samp{--}, that line is a comment.
544 For example, one can create a file called @samp{emacs.tags} with the
548 -- This is for GNU Emacs C source files
549 @{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
553 and then use it like this:
556 etags --regex=@@emacs.tags *.[ch] */*.[ch]
559 Here are some more examples. The regexps are quoted to protect them
560 from shell interpretation.
568 etags --language=none \
569 --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
570 --regex='/###key \(.*\)/\1/' \
571 --regex='/[ \t]*global[ \t].*/' \
576 Note that tags are not generated for scripts, so that you have to add
577 a line by yourself of the form @samp{###key @var{scriptname}} if you
584 etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
591 etags --language=none \
592 --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
593 --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
594 \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
598 @node Select Tags Table
599 @subsection Selecting a Tags Table
601 @vindex tags-file-name
602 @findex visit-tags-table
603 Emacs has at any time one @dfn{selected} tags table, and all the commands
604 for working with tags tables use the selected one. To select a tags table,
605 type @kbd{M-x visit-tags-table}, which reads the tags table file name as an
606 argument. The name @file{TAGS} in the default directory is used as the
609 All this command does is store the file name in the variable
610 @code{tags-file-name}. Emacs does not actually read in the tags table
611 contents until you try to use them. Setting this variable yourself is just
612 as good as using @code{visit-tags-table}. The variable's initial value is
613 @code{nil}; that value tells all the commands for working with tags tables
614 that they must ask for a tags table file name to use.
616 Using @code{visit-tags-table} when a tags table is already loaded
617 gives you a choice: you can add the new tags table to the current list
618 of tags tables, or start a new list. The tags commands use all the tags
619 tables in the current list. If you start a new list, the new tags table
620 is used @emph{instead} of others. If you add the new table to the
621 current list, it is used @emph{as well as} the others. When the tags
622 commands scan the list of tags tables, they don't always start at the
623 beginning of the list; they start with the first tags table (if any)
624 that describes the current file, proceed from there to the end of the
625 list, and then scan from the beginning of the list until they have
626 covered all the tables in the list.
628 @vindex tags-table-list
629 You can specify a precise list of tags tables by setting the variable
630 @code{tags-table-list} to a list of strings, like this:
632 @c keep this on two lines for formatting in smallbook
635 (setq tags-table-list
636 '("~/emacs" "/usr/local/lib/emacs/src"))
641 This tells the tags commands to look at the @file{TAGS} files in your
642 @file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
643 directory. The order depends on which file you are in and which tags
644 table mentions that file, as explained above.
646 Do not set both @code{tags-file-name} and @code{tags-table-list}.
649 @subsection Finding a Tag
651 The most important thing that a tags table enables you to do is to find
652 the definition of a specific tag.
655 @item M-.@: @var{tag} @key{RET}
656 Find first definition of @var{tag} (@code{find-tag}).
658 Find next alternate definition of last tag specified.
660 Go back to previous tag found.
661 @item C-M-. @var{pattern} @key{RET}
662 Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
664 Find the next tag whose name matches the last pattern used.
665 @item C-x 4 .@: @var{tag} @key{RET}
666 Find first definition of @var{tag}, but display it in another window
667 (@code{find-tag-other-window}).
668 @item C-x 5 .@: @var{tag} @key{RET}
669 Find first definition of @var{tag}, and create a new frame to select the
670 buffer (@code{find-tag-other-frame}).
672 Pop back to where you previously invoked @kbd{M-.} and friends.
677 @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
678 a specified tag. It searches through the tags table for that tag, as a
679 string, and then uses the tags table info to determine the file that the
680 definition is in and the approximate character position in the file of
681 the definition. Then @code{find-tag} visits that file, moves point to
682 the approximate character position, and searches ever-increasing
683 distances away to find the tag definition.
685 If an empty argument is given (just type @key{RET}), the balanced
686 expression in the buffer before or around point is used as the
687 @var{tag} argument. @xref{Expressions}.
689 You don't need to give @kbd{M-.} the full name of the tag; a part
690 will do. This is because @kbd{M-.} finds tags in the table which
691 contain @var{tag} as a substring. However, it prefers an exact match
692 to a substring match. To find other tags that match the same
693 substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
694 M-.}; this does not read a tag name, but continues searching the tags
695 table's text for another tag containing the same substring last used.
696 If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier
697 alternative to @kbd{C-u M-.}.
700 @findex find-tag-other-window
702 @findex find-tag-other-frame
703 Like most commands that can switch buffers, @code{find-tag} has a
704 variant that displays the new buffer in another window, and one that
705 makes a new frame for it. The former is @kbd{C-x 4 .}, which invokes
706 the command @code{find-tag-other-window}. The latter is @kbd{C-x 5 .},
707 which invokes @code{find-tag-other-frame}.
709 To move back to places you've found tags recently, use @kbd{C-u -
710 M-.}; more generally, @kbd{M-.} with a negative numeric argument. This
711 command can take you to another buffer. @kbd{C-x 4 .} with a negative
712 argument finds the previous tag location in another window.
716 @vindex find-tag-marker-ring-length
717 As well as going back to places you've found tags recently, you can go
718 back to places @emph{from where} you found them. Use @kbd{M-*}, which
719 invokes the command @code{pop-tag-mark}, for this. Typically you would
720 find and study the definition of something with @kbd{M-.} and then
721 return to where you were with @kbd{M-*}.
723 Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
724 a depth determined by the variable @code{find-tag-marker-ring-length}.
726 @findex find-tag-regexp
728 The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
729 match a specified regular expression. It is just like @kbd{M-.} except
730 that it does regexp matching instead of substring matching.
733 @subsection Searching and Replacing with Tags Tables
734 @cindex search and replace in multiple files
735 @cindex multiple-file search and replace
737 The commands in this section visit and search all the files listed in the
738 selected tags table, one by one. For these commands, the tags table serves
739 only to specify a sequence of files to search.
742 @item M-x tags-search @key{RET} @var{regexp} @key{RET}
743 Search for @var{regexp} through the files in the selected tags
745 @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
746 Perform a @code{query-replace-regexp} on each file in the selected tags table.
748 Restart one of the commands above, from the current location of point
749 (@code{tags-loop-continue}).
753 @kbd{M-x tags-search} reads a regexp using the minibuffer, then
754 searches for matches in all the files in the selected tags table, one
755 file at a time. It displays the name of the file being searched so you
756 can follow its progress. As soon as it finds an occurrence,
757 @code{tags-search} returns.
760 @findex tags-loop-continue
761 Having found one match, you probably want to find all the rest. To find
762 one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
763 @code{tags-search}. This searches the rest of the current buffer, followed
764 by the remaining files of the tags table.@refill
766 @findex tags-query-replace
767 @kbd{M-x tags-query-replace} performs a single
768 @code{query-replace-regexp} through all the files in the tags table. It
769 reads a regexp to search for and a string to replace with, just like
770 ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
771 tags-search}, but repeatedly, processing matches according to your
772 input. @xref{Replace}, for more information on query replace.
774 @vindex tags-case-fold-search
775 @cindex case-sensitivity and tags search
776 You can control the case-sensitivity of tags search commands by
777 customizing the value of the variable @code{tags-case-fold-search}. The
778 default is to use the same setting as the value of
779 @code{case-fold-search} (@pxref{Search Case}).
781 It is possible to get through all the files in the tags table with a
782 single invocation of @kbd{M-x tags-query-replace}. But often it is
783 useful to exit temporarily, which you can do with any input event that
784 has no special query replace meaning. You can resume the query replace
785 subsequently by typing @kbd{M-,}; this command resumes the last tags
786 search or replace command that you did.
788 The commands in this section carry out much broader searches than the
789 @code{find-tag} family. The @code{find-tag} commands search only for
790 definitions of tags that match your substring or regexp. The commands
791 @code{tags-search} and @code{tags-query-replace} find every occurrence
792 of the regexp, as ordinary search commands and replace commands do in
795 These commands create buffers only temporarily for the files that they
796 have to search (those which are not already visited in Emacs buffers).
797 Buffers in which no match is found are quickly killed; the others
800 It may have struck you that @code{tags-search} is a lot like
801 @code{grep}. You can also run @code{grep} itself as an inferior of
802 Emacs and have Emacs show you the matching lines one by one. This works
803 much like running a compilation; finding the source locations of the
804 @code{grep} matches works like finding the compilation errors.
808 @subsection Tags Table Inquiries
811 @item M-x list-tags @key{RET} @var{file} @key{RET}
812 Display a list of the tags defined in the program file @var{file}.
813 @item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
814 Display a list of all tags matching @var{regexp}.
818 @kbd{M-x list-tags} reads the name of one of the files described by
819 the selected tags table, and displays a list of all the tags defined in
820 that file. The ``file name'' argument is really just a string to
821 compare against the file names recorded in the tags table; it is read as
822 a string rather than as a file name. Therefore, completion and
823 defaulting are not available, and you must enter the file name the same
824 way it appears in the tags table. Do not include a directory as part of
825 the file name unless the file name recorded in the tags table includes a
829 @vindex tags-apropos-verbose
830 @kbd{M-x tags-apropos} is like @code{apropos} for tags
831 (@pxref{Apropos}). It finds all the tags in the selected tags table
832 whose entries match @var{regexp}, and displays them. If the variable
833 @code{tags-apropos-verbose} is non-@code{nil}, it displays the names
834 of the tags files together with the tag names.
836 @vindex tags-tag-face
837 @vindex tags-apropos-additional-actions
838 You can customize the appearance of the output with the face
839 @code{tags-tag-face}. You can display additional output with @kbd{M-x
840 tags-apropos} by customizing the variable
841 @code{tags-apropos-additional-actions}---see its documentation for
844 You can also use the collection of tag names to complete a symbol
845 name in the buffer. @xref{Symbol Completion}.
848 @section Merging Files with Emerge
850 @cindex merging files
852 It's not unusual for programmers to get their signals crossed and modify
853 the same program in two different directions. To recover from this
854 confusion, you need to merge the two versions. Emerge makes this
855 easier. See also @ref{Comparing Files}, for commands to compare
856 in a more manual fashion, and @ref{Top, Ediff,, ediff, The Ediff Manual}.
859 * Overview of Emerge:: How to start Emerge. Basic concepts.
860 * Submodes of Emerge:: Fast mode vs. Edit mode.
861 Skip Prefers mode and Auto Advance mode.
862 * State of Difference:: You do the merge by specifying state A or B
864 * Merge Commands:: Commands for selecting a difference,
865 changing states of differences, etc.
866 * Exiting Emerge:: What to do when you've finished the merge.
867 * Combining in Emerge:: How to keep both alternatives for a difference.
868 * Fine Points of Emerge:: Misc.
871 @node Overview of Emerge
872 @subsection Overview of Emerge
874 To start Emerge, run one of these four commands:
877 @item M-x emerge-files
879 Merge two specified files.
881 @item M-x emerge-files-with-ancestor
882 @findex emerge-files-with-ancestor
883 Merge two specified files, with reference to a common ancestor.
885 @item M-x emerge-buffers
886 @findex emerge-buffers
889 @item M-x emerge-buffers-with-ancestor
890 @findex emerge-buffers-with-ancestor
891 Merge two buffers with reference to a common ancestor in a third
895 @cindex merge buffer (Emerge)
896 @cindex A and B buffers (Emerge)
897 The Emerge commands compare two files or buffers, and display the
898 comparison in three buffers: one for each input text (the @dfn{A buffer}
899 and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging
900 takes place. The merge buffer shows the full merged text, not just the
901 differences. Wherever the two input texts differ, you can choose which
902 one of them to include in the merge buffer.
904 The Emerge commands that take input from existing buffers use only the
905 accessible portions of those buffers, if they are narrowed
908 If a common ancestor version is available, from which the two texts to
909 be merged were both derived, Emerge can use it to guess which
910 alternative is right. Wherever one current version agrees with the
911 ancestor, Emerge presumes that the other current version is a deliberate
912 change which should be kept in the merged version. Use the
913 @samp{with-ancestor} commands if you want to specify a common ancestor
914 text. These commands read three file or buffer names---variant A,
915 variant B, and the common ancestor.
917 After the comparison is done and the buffers are prepared, the
918 interactive merging starts. You control the merging by typing special
919 @dfn{merge commands} in the merge buffer. The merge buffer shows you a
920 full merged text, not just differences. For each run of differences
921 between the input texts, you can choose which one of them to keep, or
922 edit them both together.
924 The merge buffer uses a special major mode, Emerge mode, with commands
925 for making these choices. But you can also edit the buffer with
926 ordinary Emacs commands.
928 At any given time, the attention of Emerge is focused on one
929 particular difference, called the @dfn{selected} difference. This
930 difference is marked off in the three buffers like this:
934 @var{text that differs}
939 Emerge numbers all the differences sequentially and the mode
940 line always shows the number of the selected difference.
942 Normally, the merge buffer starts out with the A version of the text.
943 But when the A version of a difference agrees with the common ancestor,
944 then the B version is initially preferred for that difference.
946 Emerge leaves the merged text in the merge buffer when you exit. At
947 that point, you can save it in a file with @kbd{C-x C-w}. If you give a
948 numeric argument to @code{emerge-files} or
949 @code{emerge-files-with-ancestor}, it reads the name of the output file
950 using the minibuffer. (This is the last file name those commands read.)
951 Then exiting from Emerge saves the merged text in the output file.
953 Normally, Emerge commands save the output buffer in its file when you
954 exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not
955 save the output buffer, but you can save it yourself if you wish.
957 @node Submodes of Emerge
958 @subsection Submodes of Emerge
960 You can choose between two modes for giving merge commands: Fast mode
961 and Edit mode. In Fast mode, basic merge commands are single
962 characters, but ordinary Emacs commands are disabled. This is
963 convenient if you use only merge commands. In Edit mode, all merge
964 commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs
965 commands are also available. This allows editing the merge buffer, but
966 slows down Emerge operations.
968 Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to
969 Fast mode. The mode line indicates Edit and Fast modes with @samp{E}
972 Emerge has two additional submodes that affect how particular merge
973 commands work: Auto Advance mode and Skip Prefers mode.
975 If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands
976 advance to the next difference. This lets you go through the merge
977 faster as long as you simply choose one of the alternatives from the
978 input. The mode line indicates Auto Advance mode with @samp{A}.
980 If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands
981 skip over differences in states prefer-A and prefer-B (@pxref{State of
982 Difference}). Thus you see only differences for which neither version
983 is presumed ``correct.'' The mode line indicates Skip Prefers mode with
986 @findex emerge-auto-advance-mode
987 @findex emerge-skip-prefers-mode
988 Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or
989 clear Auto Advance mode. Use @kbd{s s}
990 (@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode.
991 These commands turn on the mode with a positive argument, turns it off
992 with a negative or zero argument, and toggle the mode with no argument.
994 @node State of Difference
995 @subsection State of a Difference
997 In the merge buffer, a difference is marked with lines of @samp{v} and
998 @samp{^} characters. Each difference has one of these seven states:
1002 The difference is showing the A version. The @kbd{a} command always
1003 produces this state; the mode line indicates it with @samp{A}.
1006 The difference is showing the B version. The @kbd{b} command always
1007 produces this state; the mode line indicates it with @samp{B}.
1011 The difference is showing the A or the B state by default, because you
1012 haven't made a choice. All differences start in the default-A state
1013 (and thus the merge buffer is a copy of the A buffer), except those for
1014 which one alternative is ``preferred'' (see below).
1016 When you select a difference, its state changes from default-A or
1017 default-B to plain A or B. Thus, the selected difference never has
1018 state default-A or default-B, and these states are never displayed in
1021 The command @kbd{d a} chooses default-A as the default state, and @kbd{d
1022 b} chooses default-B. This chosen default applies to all differences
1023 which you haven't ever selected and for which no alternative is preferred.
1024 If you are moving through the merge sequentially, the differences you
1025 haven't selected are those following the selected one. Thus, while
1026 moving sequentially, you can effectively make the A version the default
1027 for some sections of the merge buffer and the B version the default for
1028 others by using @kbd{d a} and @kbd{d b} between sections.
1032 The difference is showing the A or B state because it is
1033 @dfn{preferred}. This means that you haven't made an explicit choice,
1034 but one alternative seems likely to be right because the other
1035 alternative agrees with the common ancestor. Thus, where the A buffer
1036 agrees with the common ancestor, the B version is preferred, because
1037 chances are it is the one that was actually changed.
1039 These two states are displayed in the mode line as @samp{A*} and @samp{B*}.
1042 The difference is showing a combination of the A and B states, as a
1043 result of the @kbd{x c} or @kbd{x C} commands.
1045 Once a difference is in this state, the @kbd{a} and @kbd{b} commands
1046 don't do anything to it unless you give them a numeric argument.
1048 The mode line displays this state as @samp{comb}.
1051 @node Merge Commands
1052 @subsection Merge Commands
1054 Here are the Merge commands for Fast mode; in Edit mode, precede them
1059 Select the previous difference.
1062 Select the next difference.
1065 Choose the A version of this difference.
1068 Choose the B version of this difference.
1071 Select difference number @var{n}.
1074 Select the difference containing point. You can use this command in the
1075 merge buffer or in the A or B buffer.
1078 Quit---finish the merge.
1081 Abort---exit merging and do not save the output.
1084 Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.)
1090 Recenter (like @kbd{C-l}) all three windows.
1093 Specify part of a prefix numeric argument.
1096 Also specify part of a prefix numeric argument.
1099 Choose the A version as the default from here down in
1103 Choose the B version as the default from here down in
1107 Copy the A version of this difference into the kill ring.
1110 Copy the B version of this difference into the kill ring.
1113 Insert the A version of this difference at point.
1116 Insert the B version of this difference at point.
1119 Put point and mark around the difference.
1122 Scroll all three windows down (like @kbd{M-v}).
1125 Scroll all three windows up (like @kbd{C-v}).
1128 Scroll all three windows left (like @kbd{C-x <}).
1131 Scroll all three windows right (like @kbd{C-x >}).
1134 Reset horizontal scroll on all three windows.
1137 Shrink the merge window to one line. (Use @kbd{C-u l} to restore it
1141 Combine the two versions of this difference (@pxref{Combining in
1145 Show the names of the files/buffers Emerge is operating on, in a Help
1146 window. (Use @kbd{C-u l} to restore windows.)
1149 Join this difference with the following one.
1150 (@kbd{C-u x j} joins this difference with the previous one.)
1153 Split this difference into two differences. Before you use this
1154 command, position point in each of the three buffers at the place where
1155 you want to split the difference.
1158 Trim identical lines off the top and bottom of the difference.
1159 Such lines occur when the A and B versions are
1160 identical but differ from the ancestor version.
1163 @node Exiting Emerge
1164 @subsection Exiting Emerge
1166 The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing
1167 the results into the output file if you specified one. It restores the
1168 A and B buffers to their proper contents, or kills them if they were
1169 created by Emerge and you haven't changed them. It also disables the
1170 Emerge commands in the merge buffer, since executing them later could
1171 damage the contents of the various buffers.
1173 @kbd{C-]} aborts the merge. This means exiting without writing the
1174 output file. If you didn't specify an output file, then there is no
1175 real difference between aborting and finishing the merge.
1177 If the Emerge command was called from another Lisp program, then its
1178 return value is @code{t} for successful completion, or @code{nil} if you
1181 @node Combining in Emerge
1182 @subsection Combining the Two Versions
1184 Sometimes you want to keep @emph{both} alternatives for a particular
1185 difference. To do this, use @kbd{x c}, which edits the merge buffer
1191 @var{version from A buffer}
1193 @var{version from B buffer}
1194 #endif /* not NEW */
1199 @vindex emerge-combine-versions-template
1200 While this example shows C preprocessor conditionals delimiting the two
1201 alternative versions, you can specify the strings to use by setting
1202 the variable @code{emerge-combine-versions-template} to a string of your
1203 choice. In the string, @samp{%a} says where to put version A, and
1204 @samp{%b} says where to put version B. The default setting, which
1205 produces the results shown above, looks like this:
1209 "#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"
1213 @node Fine Points of Emerge
1214 @subsection Fine Points of Emerge
1216 During the merge, you mustn't try to edit the A and B buffers yourself.
1217 Emerge modifies them temporarily, but ultimately puts them back the way
1220 You can have any number of merges going at once---just don't use any one
1221 buffer as input to more than one merge at once, since the temporary
1222 changes made in these buffers would get in each other's way.
1224 Starting Emerge can take a long time because it needs to compare the
1225 files fully. Emacs can't do anything else until @code{diff} finishes.
1226 Perhaps in the future someone will change Emerge to do the comparison in
1227 the background when the input files are large---then you could keep on
1228 doing other things with Emacs until Emerge is ready to accept
1231 @vindex emerge-startup-hook
1232 After setting up the merge, Emerge runs the hook
1233 @code{emerge-startup-hook} (@pxref{Hooks}).