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 PostScript code, the tags are the functions.
350 In Prolog code, a tag name appears at the left margin.
353 In Python code, @code{def} or @code{class} at the beginning of a line
357 You can also generate tags based on regexp matching (@pxref{Etags
358 Regexps}) to handle other formats and languages.
360 @node Create Tags Table
361 @subsection Creating Tags Tables
362 @cindex @code{etags} program
364 The @code{etags} program is used to create a tags table file. It knows
365 the syntax of several languages, as described in
367 the previous section.
372 Here is how to run @code{etags}:
375 etags @var{inputfiles}@dots{}
379 The @code{etags} program reads the specified files, and writes a tags
380 table named @file{TAGS} in the current working directory.
382 If the specified files don't exist, @code{etags} looks for
383 compressed versions of them and uncompresses them to read them. Under
384 MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz}
385 if it is given @samp{mycode.c} on the command line and @file{mycode.c}
388 @code{etags} recognizes the language used in an input file based on
389 its file name and contents. You can specify the language with the
390 @samp{--language=@var{name}} option, described below.
392 If the tags table data become outdated due to changes in the files
393 described in the table, the way to update the tags table is the same
394 way it was made in the first place. If the tags table fails to record
395 a tag, or records it for the wrong file, then Emacs cannot possibly
396 find its definition until you update the tags table. However, if the
397 position recorded in the tags table becomes a little bit wrong (due to
398 other editing), the only consequence is a slight delay in finding the
399 tag. Even if the stored position is very far wrong, Emacs will still
400 find the tag, after searching most of the file for it. Even that
401 delay is hardly noticeable with today's computers.
403 So you should update a tags table when you define new tags that you want
404 to have listed, or when you move tag definitions from one file to another,
405 or when changes become substantial. Normally there is no need to update
406 the tags table after each edit, or even every day.
408 One tags table can virtually include another. Specify the included
409 tags file name with the @samp{--include=@var{file}} option when
410 creating the file that is to include it. The latter file then acts as
411 if it covered all the source files specified in the included file, as
412 well as the files it directly contains.
414 If you specify the source files with relative file names when you run
415 @code{etags}, the tags file will contain file names relative to the
416 directory where the tags file was initially written. This way, you can
417 move an entire directory tree containing both the tags file and the
418 source files, and the tags file will still refer correctly to the source
421 If you specify absolute file names as arguments to @code{etags}, then
422 the tags file will contain absolute file names. This way, the tags file
423 will still refer to the same files even if you move it, as long as the
424 source files remain in the same place. Absolute file names start with
425 @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
427 When you want to make a tags table from a great number of files, you
428 may have problems listing them on the command line, because some systems
429 have a limit on its length. The simplest way to circumvent this limit
430 is to tell @code{etags} to read the file names from its standard input,
431 by typing a dash in place of the file names, like this:
434 find . -name "*.[chCH]" -print | etags -
437 Use the option @samp{--language=@var{name}} to specify the language
438 explicitly. You can intermix these options with file names; each one
439 applies to the file names that follow it. Specify
440 @samp{--language=auto} to tell @code{etags} to resume guessing the
441 language from the file names and file contents. Specify
442 @samp{--language=none} to turn off language-specific processing
443 entirely; then @code{etags} recognizes tags by regexp matching alone
444 (@pxref{Etags Regexps}).
446 @samp{etags --help} prints the list of the languages @code{etags}
447 knows, and the file name rules for guessing the language. It also prints
448 a list of all the available @code{etags} options, together with a short
452 @subsection Etags Regexps
454 The @samp{--regex} option provides a general way of recognizing tags
455 based on regexp matching. You can freely intermix it with file names.
456 Each @samp{--regex} option adds to the preceding ones, and applies only
457 to the following files. The syntax is:
460 --regex=/@var{tagregexp}[/@var{nameregexp}]/
464 where @var{tagregexp} is used to match the lines to tag. It is always
465 anchored, that is, it behaves as if preceded by @samp{^}. If you want
466 to account for indentation, just match any initial number of blanks by
467 beginning your regular expression with @samp{[ \t]*}. In the regular
468 expressions, @samp{\} quotes the next character, and @samp{\t} stands
469 for the tab character. Note that @code{etags} does not handle the other
470 C escape sequences for special characters.
472 @cindex interval operator (in regexps)
473 The syntax of regular expressions in @code{etags} is the same as in
474 Emacs, augmented with the @dfn{interval operator}, which works as in
475 @code{grep} and @code{ed}. The syntax of an interval operator is
476 @samp{\@{@var{m},@var{n}\@}}, and its meaning is to match the preceding
477 expression at least @var{m} times and up to @var{n} times.
479 You should not match more characters with @var{tagregexp} than that
480 needed to recognize what you want to tag. If the match is such that
481 more characters than needed are unavoidably matched by @var{tagregexp}
482 (as will usually be the case), you should add a @var{nameregexp}, to
483 pick out just the tag. This will enable Emacs to find tags more
484 accurately and to do completion on tag names more reliably. You can
485 find some examples below.
487 The option @samp{--ignore-case-regex} (or @samp{-c}) works like
488 @samp{--regex}, except that matching ignores case. This is
489 appropriate for certain programming languages.
491 The @samp{-R} option deletes all the regexps defined with
492 @samp{--regex} options. It applies to the file names following it, as
493 you can see from the following example:
496 etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \
497 bar.ber -R --lang=lisp los.er
501 Here @code{etags} chooses the parsing language for @file{voo.doo} and
502 @file{bar.ber} according to their contents. @code{etags} also uses
503 @var{reg1} to recognize additional tags in @file{voo.doo}, and both
504 @var{reg1} and @var{reg2} to recognize additional tags in
505 @file{bar.ber}. @code{etags} uses the Lisp tags rules, and no regexp
506 matching, to recognize tags in @file{los.er}.
508 You can specify a regular expression for a particular language, by
509 writing @samp{@{lang@}} in front of it. Then @code{etags} will use
510 the regular expression only for files of that language. (@samp{etags
511 --help} prints the list of languages recognized by @code{etags}.) The
512 following example tags the @code{DEFVAR} macros in the Emacs source
513 files, for the C language only:
516 --regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
520 This feature is particularly useful when you store a list of regular
521 expressions in a file. The following option syntax instructs
522 @code{etags} to read two files of regular expressions. The regular
523 expressions contained in the second file are matched without regard to
527 --regex=@@first-file --ignore-case-regex=@@second-file
531 A regex file contains one regular expressions per line. Empty lines,
532 and lines beginning with space or tab are ignored. When the first
533 character in a line is @samp{@@}, @code{etags} assumes that the rest
534 of the line is the name of a file of regular expressions; thus, one
535 such file can include another file. All the other lines are taken to
536 be regular expressions. If the first non-whitespace text on the line
537 is @samp{--}, that line is a comment.
539 For example, one can create a file called @samp{emacs.tags} with the
543 -- This is for GNU Emacs C source files
544 @{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
548 and then use it like this:
551 etags --regex=@@emacs.tags *.[ch] */*.[ch]
554 Here are some more examples. The regexps are quoted to protect them
555 from shell interpretation.
563 etags --language=none \
564 --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
565 --regex='/###key \(.*\)/\1/' \
566 --regex='/[ \t]*global[ \t].*/' \
571 Note that tags are not generated for scripts, so that you have to add
572 a line by yourself of the form @samp{###key @var{scriptname}} if you
579 etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
586 etags --language=none \
587 --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
588 --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
589 \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
593 @node Select Tags Table
594 @subsection Selecting a Tags Table
596 @vindex tags-file-name
597 @findex visit-tags-table
598 Emacs has at any time one @dfn{selected} tags table, and all the commands
599 for working with tags tables use the selected one. To select a tags table,
600 type @kbd{M-x visit-tags-table}, which reads the tags table file name as an
601 argument. The name @file{TAGS} in the default directory is used as the
604 All this command does is store the file name in the variable
605 @code{tags-file-name}. Emacs does not actually read in the tags table
606 contents until you try to use them. Setting this variable yourself is just
607 as good as using @code{visit-tags-table}. The variable's initial value is
608 @code{nil}; that value tells all the commands for working with tags tables
609 that they must ask for a tags table file name to use.
611 Using @code{visit-tags-table} when a tags table is already loaded
612 gives you a choice: you can add the new tags table to the current list
613 of tags tables, or start a new list. The tags commands use all the tags
614 tables in the current list. If you start a new list, the new tags table
615 is used @emph{instead} of others. If you add the new table to the
616 current list, it is used @emph{as well as} the others. When the tags
617 commands scan the list of tags tables, they don't always start at the
618 beginning of the list; they start with the first tags table (if any)
619 that describes the current file, proceed from there to the end of the
620 list, and then scan from the beginning of the list until they have
621 covered all the tables in the list.
623 @vindex tags-table-list
624 You can specify a precise list of tags tables by setting the variable
625 @code{tags-table-list} to a list of strings, like this:
627 @c keep this on two lines for formatting in smallbook
630 (setq tags-table-list
631 '("~/emacs" "/usr/local/lib/emacs/src"))
636 This tells the tags commands to look at the @file{TAGS} files in your
637 @file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
638 directory. The order depends on which file you are in and which tags
639 table mentions that file, as explained above.
641 Do not set both @code{tags-file-name} and @code{tags-table-list}.
644 @subsection Finding a Tag
646 The most important thing that a tags table enables you to do is to find
647 the definition of a specific tag.
650 @item M-.@: @var{tag} @key{RET}
651 Find first definition of @var{tag} (@code{find-tag}).
653 Find next alternate definition of last tag specified.
655 Go back to previous tag found.
656 @item C-M-. @var{pattern} @key{RET}
657 Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
659 Find the next tag whose name matches the last pattern used.
660 @item C-x 4 .@: @var{tag} @key{RET}
661 Find first definition of @var{tag}, but display it in another window
662 (@code{find-tag-other-window}).
663 @item C-x 5 .@: @var{tag} @key{RET}
664 Find first definition of @var{tag}, and create a new frame to select the
665 buffer (@code{find-tag-other-frame}).
667 Pop back to where you previously invoked @kbd{M-.} and friends.
672 @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
673 a specified tag. It searches through the tags table for that tag, as a
674 string, and then uses the tags table info to determine the file that the
675 definition is in and the approximate character position in the file of
676 the definition. Then @code{find-tag} visits that file, moves point to
677 the approximate character position, and searches ever-increasing
678 distances away to find the tag definition.
680 If an empty argument is given (just type @key{RET}), the balanced
681 expression in the buffer before or around point is used as the
682 @var{tag} argument. @xref{Expressions}.
684 You don't need to give @kbd{M-.} the full name of the tag; a part
685 will do. This is because @kbd{M-.} finds tags in the table which
686 contain @var{tag} as a substring. However, it prefers an exact match
687 to a substring match. To find other tags that match the same
688 substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
689 M-.}; this does not read a tag name, but continues searching the tags
690 table's text for another tag containing the same substring last used.
691 If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier
692 alternative to @kbd{C-u M-.}.
695 @findex find-tag-other-window
697 @findex find-tag-other-frame
698 Like most commands that can switch buffers, @code{find-tag} has a
699 variant that displays the new buffer in another window, and one that
700 makes a new frame for it. The former is @kbd{C-x 4 .}, which invokes
701 the command @code{find-tag-other-window}. The latter is @kbd{C-x 5 .},
702 which invokes @code{find-tag-other-frame}.
704 To move back to places you've found tags recently, use @kbd{C-u -
705 M-.}; more generally, @kbd{M-.} with a negative numeric argument. This
706 command can take you to another buffer. @kbd{C-x 4 .} with a negative
707 argument finds the previous tag location in another window.
711 @vindex find-tag-marker-ring-length
712 As well as going back to places you've found tags recently, you can go
713 back to places @emph{from where} you found them. Use @kbd{M-*}, which
714 invokes the command @code{pop-tag-mark}, for this. Typically you would
715 find and study the definition of something with @kbd{M-.} and then
716 return to where you were with @kbd{M-*}.
718 Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
719 a depth determined by the variable @code{find-tag-marker-ring-length}.
721 @findex find-tag-regexp
723 The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
724 match a specified regular expression. It is just like @kbd{M-.} except
725 that it does regexp matching instead of substring matching.
728 @subsection Searching and Replacing with Tags Tables
729 @cindex search and replace in multiple files
730 @cindex multiple-file search and replace
732 The commands in this section visit and search all the files listed in the
733 selected tags table, one by one. For these commands, the tags table serves
734 only to specify a sequence of files to search.
737 @item M-x tags-search @key{RET} @var{regexp} @key{RET}
738 Search for @var{regexp} through the files in the selected tags
740 @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
741 Perform a @code{query-replace-regexp} on each file in the selected tags table.
743 Restart one of the commands above, from the current location of point
744 (@code{tags-loop-continue}).
748 @kbd{M-x tags-search} reads a regexp using the minibuffer, then
749 searches for matches in all the files in the selected tags table, one
750 file at a time. It displays the name of the file being searched so you
751 can follow its progress. As soon as it finds an occurrence,
752 @code{tags-search} returns.
755 @findex tags-loop-continue
756 Having found one match, you probably want to find all the rest. To find
757 one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
758 @code{tags-search}. This searches the rest of the current buffer, followed
759 by the remaining files of the tags table.@refill
761 @findex tags-query-replace
762 @kbd{M-x tags-query-replace} performs a single
763 @code{query-replace-regexp} through all the files in the tags table. It
764 reads a regexp to search for and a string to replace with, just like
765 ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
766 tags-search}, but repeatedly, processing matches according to your
767 input. @xref{Replace}, for more information on query replace.
769 @vindex tags-case-fold-search
770 @cindex case-sensitivity and tags search
771 You can control the case-sensitivity of tags search commands by
772 customizing the value of the variable @code{tags-case-fold-search}. The
773 default is to use the same setting as the value of
774 @code{case-fold-search} (@pxref{Search Case}).
776 It is possible to get through all the files in the tags table with a
777 single invocation of @kbd{M-x tags-query-replace}. But often it is
778 useful to exit temporarily, which you can do with any input event that
779 has no special query replace meaning. You can resume the query replace
780 subsequently by typing @kbd{M-,}; this command resumes the last tags
781 search or replace command that you did.
783 The commands in this section carry out much broader searches than the
784 @code{find-tag} family. The @code{find-tag} commands search only for
785 definitions of tags that match your substring or regexp. The commands
786 @code{tags-search} and @code{tags-query-replace} find every occurrence
787 of the regexp, as ordinary search commands and replace commands do in
790 These commands create buffers only temporarily for the files that they
791 have to search (those which are not already visited in Emacs buffers).
792 Buffers in which no match is found are quickly killed; the others
795 It may have struck you that @code{tags-search} is a lot like
796 @code{grep}. You can also run @code{grep} itself as an inferior of
797 Emacs and have Emacs show you the matching lines one by one. This works
798 much like running a compilation; finding the source locations of the
799 @code{grep} matches works like finding the compilation errors.
803 @subsection Tags Table Inquiries
806 @item M-x list-tags @key{RET} @var{file} @key{RET}
807 Display a list of the tags defined in the program file @var{file}.
808 @item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
809 Display a list of all tags matching @var{regexp}.
813 @kbd{M-x list-tags} reads the name of one of the files described by
814 the selected tags table, and displays a list of all the tags defined in
815 that file. The ``file name'' argument is really just a string to
816 compare against the file names recorded in the tags table; it is read as
817 a string rather than as a file name. Therefore, completion and
818 defaulting are not available, and you must enter the file name the same
819 way it appears in the tags table. Do not include a directory as part of
820 the file name unless the file name recorded in the tags table includes a
824 @vindex tags-apropos-verbose
825 @kbd{M-x tags-apropos} is like @code{apropos} for tags
826 (@pxref{Apropos}). It finds all the tags in the selected tags table
827 whose entries match @var{regexp}, and displays them. If the variable
828 @code{tags-apropos-verbose} is non-@code{nil}, it displays the names
829 of the tags files together with the tag names.
831 @vindex tags-tag-face
832 @vindex tags-apropos-additional-actions
833 You can customize the appearance of the output with the face
834 @code{tags-tag-face}. You can display additional output with @kbd{M-x
835 tags-apropos} by customizing the variable
836 @code{tags-apropos-additional-actions}---see its documentation for
839 You can also use the collection of tag names to complete a symbol
840 name in the buffer. @xref{Symbol Completion}.
843 @section Merging Files with Emerge
845 @cindex merging files
847 It's not unusual for programmers to get their signals crossed and modify
848 the same program in two different directions. To recover from this
849 confusion, you need to merge the two versions. Emerge makes this
850 easier. See also @ref{Comparing Files}, for commands to compare
851 in a more manual fashion, and @ref{Top, Ediff,, ediff, The Ediff Manual}.
854 * Overview of Emerge:: How to start Emerge. Basic concepts.
855 * Submodes of Emerge:: Fast mode vs. Edit mode.
856 Skip Prefers mode and Auto Advance mode.
857 * State of Difference:: You do the merge by specifying state A or B
859 * Merge Commands:: Commands for selecting a difference,
860 changing states of differences, etc.
861 * Exiting Emerge:: What to do when you've finished the merge.
862 * Combining in Emerge:: How to keep both alternatives for a difference.
863 * Fine Points of Emerge:: Misc.
866 @node Overview of Emerge
867 @subsection Overview of Emerge
869 To start Emerge, run one of these four commands:
872 @item M-x emerge-files
874 Merge two specified files.
876 @item M-x emerge-files-with-ancestor
877 @findex emerge-files-with-ancestor
878 Merge two specified files, with reference to a common ancestor.
880 @item M-x emerge-buffers
881 @findex emerge-buffers
884 @item M-x emerge-buffers-with-ancestor
885 @findex emerge-buffers-with-ancestor
886 Merge two buffers with reference to a common ancestor in a third
890 @cindex merge buffer (Emerge)
891 @cindex A and B buffers (Emerge)
892 The Emerge commands compare two files or buffers, and display the
893 comparison in three buffers: one for each input text (the @dfn{A buffer}
894 and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging
895 takes place. The merge buffer shows the full merged text, not just the
896 differences. Wherever the two input texts differ, you can choose which
897 one of them to include in the merge buffer.
899 The Emerge commands that take input from existing buffers use only the
900 accessible portions of those buffers, if they are narrowed
903 If a common ancestor version is available, from which the two texts to
904 be merged were both derived, Emerge can use it to guess which
905 alternative is right. Wherever one current version agrees with the
906 ancestor, Emerge presumes that the other current version is a deliberate
907 change which should be kept in the merged version. Use the
908 @samp{with-ancestor} commands if you want to specify a common ancestor
909 text. These commands read three file or buffer names---variant A,
910 variant B, and the common ancestor.
912 After the comparison is done and the buffers are prepared, the
913 interactive merging starts. You control the merging by typing special
914 @dfn{merge commands} in the merge buffer. The merge buffer shows you a
915 full merged text, not just differences. For each run of differences
916 between the input texts, you can choose which one of them to keep, or
917 edit them both together.
919 The merge buffer uses a special major mode, Emerge mode, with commands
920 for making these choices. But you can also edit the buffer with
921 ordinary Emacs commands.
923 At any given time, the attention of Emerge is focused on one
924 particular difference, called the @dfn{selected} difference. This
925 difference is marked off in the three buffers like this:
929 @var{text that differs}
934 Emerge numbers all the differences sequentially and the mode
935 line always shows the number of the selected difference.
937 Normally, the merge buffer starts out with the A version of the text.
938 But when the A version of a difference agrees with the common ancestor,
939 then the B version is initially preferred for that difference.
941 Emerge leaves the merged text in the merge buffer when you exit. At
942 that point, you can save it in a file with @kbd{C-x C-w}. If you give a
943 numeric argument to @code{emerge-files} or
944 @code{emerge-files-with-ancestor}, it reads the name of the output file
945 using the minibuffer. (This is the last file name those commands read.)
946 Then exiting from Emerge saves the merged text in the output file.
948 Normally, Emerge commands save the output buffer in its file when you
949 exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not
950 save the output buffer, but you can save it yourself if you wish.
952 @node Submodes of Emerge
953 @subsection Submodes of Emerge
955 You can choose between two modes for giving merge commands: Fast mode
956 and Edit mode. In Fast mode, basic merge commands are single
957 characters, but ordinary Emacs commands are disabled. This is
958 convenient if you use only merge commands. In Edit mode, all merge
959 commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs
960 commands are also available. This allows editing the merge buffer, but
961 slows down Emerge operations.
963 Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to
964 Fast mode. The mode line indicates Edit and Fast modes with @samp{E}
967 Emerge has two additional submodes that affect how particular merge
968 commands work: Auto Advance mode and Skip Prefers mode.
970 If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands
971 advance to the next difference. This lets you go through the merge
972 faster as long as you simply choose one of the alternatives from the
973 input. The mode line indicates Auto Advance mode with @samp{A}.
975 If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands
976 skip over differences in states prefer-A and prefer-B (@pxref{State of
977 Difference}). Thus you see only differences for which neither version
978 is presumed ``correct.'' The mode line indicates Skip Prefers mode with
981 @findex emerge-auto-advance-mode
982 @findex emerge-skip-prefers-mode
983 Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or
984 clear Auto Advance mode. Use @kbd{s s}
985 (@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode.
986 These commands turn on the mode with a positive argument, turns it off
987 with a negative or zero argument, and toggle the mode with no argument.
989 @node State of Difference
990 @subsection State of a Difference
992 In the merge buffer, a difference is marked with lines of @samp{v} and
993 @samp{^} characters. Each difference has one of these seven states:
997 The difference is showing the A version. The @kbd{a} command always
998 produces this state; the mode line indicates it with @samp{A}.
1001 The difference is showing the B version. The @kbd{b} command always
1002 produces this state; the mode line indicates it with @samp{B}.
1006 The difference is showing the A or the B state by default, because you
1007 haven't made a choice. All differences start in the default-A state
1008 (and thus the merge buffer is a copy of the A buffer), except those for
1009 which one alternative is ``preferred'' (see below).
1011 When you select a difference, its state changes from default-A or
1012 default-B to plain A or B. Thus, the selected difference never has
1013 state default-A or default-B, and these states are never displayed in
1016 The command @kbd{d a} chooses default-A as the default state, and @kbd{d
1017 b} chooses default-B. This chosen default applies to all differences
1018 which you haven't ever selected and for which no alternative is preferred.
1019 If you are moving through the merge sequentially, the differences you
1020 haven't selected are those following the selected one. Thus, while
1021 moving sequentially, you can effectively make the A version the default
1022 for some sections of the merge buffer and the B version the default for
1023 others by using @kbd{d a} and @kbd{d b} between sections.
1027 The difference is showing the A or B state because it is
1028 @dfn{preferred}. This means that you haven't made an explicit choice,
1029 but one alternative seems likely to be right because the other
1030 alternative agrees with the common ancestor. Thus, where the A buffer
1031 agrees with the common ancestor, the B version is preferred, because
1032 chances are it is the one that was actually changed.
1034 These two states are displayed in the mode line as @samp{A*} and @samp{B*}.
1037 The difference is showing a combination of the A and B states, as a
1038 result of the @kbd{x c} or @kbd{x C} commands.
1040 Once a difference is in this state, the @kbd{a} and @kbd{b} commands
1041 don't do anything to it unless you give them a numeric argument.
1043 The mode line displays this state as @samp{comb}.
1046 @node Merge Commands
1047 @subsection Merge Commands
1049 Here are the Merge commands for Fast mode; in Edit mode, precede them
1054 Select the previous difference.
1057 Select the next difference.
1060 Choose the A version of this difference.
1063 Choose the B version of this difference.
1066 Select difference number @var{n}.
1069 Select the difference containing point. You can use this command in the
1070 merge buffer or in the A or B buffer.
1073 Quit---finish the merge.
1076 Abort---exit merging and do not save the output.
1079 Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.)
1085 Recenter (like @kbd{C-l}) all three windows.
1088 Specify part of a prefix numeric argument.
1091 Also specify part of a prefix numeric argument.
1094 Choose the A version as the default from here down in
1098 Choose the B version as the default from here down in
1102 Copy the A version of this difference into the kill ring.
1105 Copy the B version of this difference into the kill ring.
1108 Insert the A version of this difference at point.
1111 Insert the B version of this difference at point.
1114 Put point and mark around the difference.
1117 Scroll all three windows down (like @kbd{M-v}).
1120 Scroll all three windows up (like @kbd{C-v}).
1123 Scroll all three windows left (like @kbd{C-x <}).
1126 Scroll all three windows right (like @kbd{C-x >}).
1129 Reset horizontal scroll on all three windows.
1132 Shrink the merge window to one line. (Use @kbd{C-u l} to restore it
1136 Combine the two versions of this difference (@pxref{Combining in
1140 Show the names of the files/buffers Emerge is operating on, in a Help
1141 window. (Use @kbd{C-u l} to restore windows.)
1144 Join this difference with the following one.
1145 (@kbd{C-u x j} joins this difference with the previous one.)
1148 Split this difference into two differences. Before you use this
1149 command, position point in each of the three buffers at the place where
1150 you want to split the difference.
1153 Trim identical lines off the top and bottom of the difference.
1154 Such lines occur when the A and B versions are
1155 identical but differ from the ancestor version.
1158 @node Exiting Emerge
1159 @subsection Exiting Emerge
1161 The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing
1162 the results into the output file if you specified one. It restores the
1163 A and B buffers to their proper contents, or kills them if they were
1164 created by Emerge and you haven't changed them. It also disables the
1165 Emerge commands in the merge buffer, since executing them later could
1166 damage the contents of the various buffers.
1168 @kbd{C-]} aborts the merge. This means exiting without writing the
1169 output file. If you didn't specify an output file, then there is no
1170 real difference between aborting and finishing the merge.
1172 If the Emerge command was called from another Lisp program, then its
1173 return value is @code{t} for successful completion, or @code{nil} if you
1176 @node Combining in Emerge
1177 @subsection Combining the Two Versions
1179 Sometimes you want to keep @emph{both} alternatives for a particular
1180 difference. To do this, use @kbd{x c}, which edits the merge buffer
1186 @var{version from A buffer}
1188 @var{version from B buffer}
1189 #endif /* not NEW */
1194 @vindex emerge-combine-versions-template
1195 While this example shows C preprocessor conditionals delimiting the two
1196 alternative versions, you can specify the strings to use by setting
1197 the variable @code{emerge-combine-versions-template} to a string of your
1198 choice. In the string, @samp{%a} says where to put version A, and
1199 @samp{%b} says where to put version B. The default setting, which
1200 produces the results shown above, looks like this:
1204 "#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"
1208 @node Fine Points of Emerge
1209 @subsection Fine Points of Emerge
1211 During the merge, you mustn't try to edit the A and B buffers yourself.
1212 Emerge modifies them temporarily, but ultimately puts them back the way
1215 You can have any number of merges going at once---just don't use any one
1216 buffer as input to more than one merge at once, since the temporary
1217 changes made in these buffers would get in each other's way.
1219 Starting Emerge can take a long time because it needs to compare the
1220 files fully. Emacs can't do anything else until @code{diff} finishes.
1221 Perhaps in the future someone will change Emerge to do the comparison in
1222 the background when the input files are large---then you could keep on
1223 doing other things with Emacs until Emerge is ready to accept
1226 @vindex emerge-startup-hook
1227 After setting up the merge, Emerge runs the hook
1228 @code{emerge-startup-hook} (@pxref{Hooks}).