maintaining.texi 48 KB
Newer Older
1 2 3 4 5 6 7 8 9 10
@c This is part of the Emacs manual.
@c Copyright (C) 1985,86,87,93,94,95,97,99,00,2001 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Maintaining, Abbrevs, Building, Top
@chapter Maintaining Programs
@cindex Lisp editing
@cindex C editing
@cindex program editing

  This chapter describes Emacs features for maintaining programs.  The
Richard M. Stallman's avatar
Richard M. Stallman committed
11 12
version control features (@pxref{Version Control}) are also
particularly useful for this purpose.
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41

* Change Log::	        Maintaining a change history for your program.
* Tags::	        Go direct to any function in your program in one
			  command.  Tags remembers which file it is in.
* Emerge::	        A convenient way of merging two versions of a program.
@end menu

@node Change Log
@section Change Logs

@cindex change log
@kindex C-x 4 a
@findex add-change-log-entry-other-window
  The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
file for the file you are editing
(@code{add-change-log-entry-other-window}).  If that file is actually
a backup file, it makes an entry appropriate for the file's
parent---that is useful for making log entries for functions that
have been deleted in the current version.

  A change log file contains a chronological record of when and why you
have changed a program, consisting of a sequence of entries describing
individual changes.  Normally it is kept in a file called
@file{ChangeLog} in the same directory as the file you are editing, or
one of its parent directories.  A single @file{ChangeLog} file can
record changes for all the files in its directory and all its

42 43 44 45 46 47 48 49 50 51 52 53
  You should put a copyright notice and permission notice at the
end of the change log file.  Here is an example:

Copyright 1997, 1998 Free Software Foundation, Inc.
Copying and distribution of this file, with or without modification, are
permitted provided the copyright notice and this notice are preserved.
@end example

Of course, you should substitute the proper years and copyright holder.

54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105
  A change log entry starts with a header line that contains the
current date, your name, and your email address (taken from the
variable @code{user-mail-address}).  Aside from these header lines,
every line in the change log starts with a space or a tab.  The bulk
of the entry consists of @dfn{items}, each of which starts with a line
starting with whitespace and a star.  Here are two entries, both dated
in May 1993, each with two items:

@end iftex
1993-05-25  Richard Stallman  <>

        * man.el: Rename symbols `man-*' to `Man-*'.
        (manual-entry): Make prompt string clearer.

        * simple.el (blink-matching-paren-distance):
        Change default to 12,000.

1993-05-24  Richard Stallman  <>

        * vc.el (minor-mode-map-alist): Don't use it if it's void.
        (vc-cancel-version): Doc fix.
@end smallexample

  One entry can describe several changes; each change should have its
own item.  Normally there should be a blank line between items.  When
items are related (parts of the same change, in different places), group
them by leaving no blank line between them.  The second entry above
contains two items grouped in this way.

  @kbd{C-x 4 a} visits the change log file and creates a new entry
unless the most recent entry is for today's date and your name.  It
also creates a new item for the current file.  For many languages, it
can even guess the name of the function or other object that was

@vindex add-log-keep-changes-together
  When the option @code{add-log-keep-changes-together} is
non-@code{nil}, @kbd{C-x 4 a} adds to any existing entry for the file
rather than starting a new entry.

@vindex change-log-version-info-enabled
@vindex change-log-version-number-regexp-list
@cindex file version in change log entries
  If the value of the variable @code{change-log-version-info-enabled}
is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the
change log entry.  It finds the version number by searching the first
ten percent of the file, using regular expressions from the variable

106 107 108 109 110
@vindex add-log-always-start-new-record
  If @code{add-log-always-start-new-record} is non-@code{nil},
@kbd{C-x 4 a} always makes a new entry, even if the last entry
was made by you and on the same date.

111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142
@cindex Change Log mode
@findex change-log-mode
  The change log file is visited in Change Log mode.  In this major
mode, each bunch of grouped items counts as one paragraph, and each
entry is considered a page.  This facilitates editing the entries.
@kbd{C-j} and auto-fill indent each new line like the previous line;
this is convenient for entering the contents of an entry.

@findex change-log-merge
  You can use the command @kbd{M-x change-log-merge} to merge other
log files into a buffer in Change Log Mode, preserving the date
ordering of entries.

@findex change-log-redate
@cindex converting change log date style
  Versions of Emacs before 20.1 used a different format for the time of
the change log entry:

Fri May 25 11:23:23 1993 Richard Stallman  <>
@end smallexample

The @kbd{M-x change-log-redate} command converts all the old-style
date entries in the change log file visited in the current buffer to
the new format, to make the file uniform in style.  This is handy when
entries are contributed by many different people, some of whom use old
versions of Emacs.

  Version control systems are another way to keep track of changes in your
program and keep a change log.  @xref{Log Buffer}.

143 144 145 146
@c This is commented out because the command is specific
@c to maintenance of Emacs itself.

147 148 149 150 151 152 153 154 155 156 157
@node Authors
@section @file{AUTHORS} files
@cindex @file{AUTHORS} file

  Programs which have many contributors usually include a file named
@file{AUTHORS} in their distribution, which lists the individual
contributions.  Emacs has a special command for maintaining the
@file{AUTHORS} file that is part of the Emacs distribution.

@findex authors
  The @kbd{M-x authors} command prompts for the name of the root of the
Gerd Moellmann's avatar
Gerd Moellmann committed
Emacs source directory.  It then scans @file{ChangeLog} files and Lisp
source files under that directory for information about authors of
Richard M. Stallman's avatar
Richard M. Stallman committed
individual packages, and people who made changes in source files, and
161 162
puts the information it gleans into a buffer named @samp{*Authors*}.
You can then edit the contents of that buffer and merge it with the
Eli Zaretskii's avatar
Eli Zaretskii committed
existing @file{AUTHORS} file.
164 165 166 167 168

  Do not assume that this command finds all the contributors; don't
assume that a person not listed in the output was not a contributor.
If you merged in someone's contribution and did not put his name
in the change log, he won't show up in @kbd{M-x authors} either.
@end ignore
170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186

@node Tags
@section Tags Tables
@cindex tags table

  A @dfn{tags table} is a description of how a multi-file program is
broken up into files.  It lists the names of the component files and the
names and positions of the functions (or other named subunits) in each
file.  Grouping the related files makes it possible to search or replace
through all the files with one command.  Recording the function names
and positions makes possible the @kbd{M-.} command which finds the
definition of a function by looking up which of the files it is in.

  Tags tables are stored in files called @dfn{tags table files}.  The
conventional name for a tags table file is @file{TAGS}.

  Each entry in the tags table records the name of one tag, the name of the
187 188
file that the tag is defined in (implicitly), and the position in that
file of the tag's definition.  When a file parsed by @code{etags} is
189 190 191
generated from a different source file, like a C file generated from a
Cweb source file, the tags of the parsed file reference the source
192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251

  Just what names from the described files are recorded in the tags table
depends on the programming language of the described file.  They
normally include all file names, functions and subroutines, and may
also include global variables, data types, and anything else
convenient.  Each name recorded is called a @dfn{tag}.

@cindex C++ class browser, tags
@cindex tags, C++
@cindex class browser, C++
@cindex Ebrowse
  See also the Ebrowse facility, which is tailored for C++.
@xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}.

* Tag Syntax::		Tag syntax for various types of code and text files.
* Create Tags Table::	Creating a tags table with @code{etags}.
* Etags Regexps::       Create arbitrary tags using regular expressions.
* Select Tags Table::	How to visit a tags table.
* Find Tag::		Commands to find the definition of a specific tag.
* Tags Search::		Using a tags table for searching and replacing.
* List Tags::		Listing and finding tags defined in a file.
@end menu

@node Tag Syntax
@subsection Source File Tag Syntax

  Here is how tag syntax is defined for the most popular languages:

@itemize @bullet
In C code, any C function or typedef is a tag, and so are definitions of
@code{struct}, @code{union} and @code{enum}.
@code{#define} macro definitions and @code{enum} constants are also
tags, unless you specify @samp{--no-defines} when making the tags table.
Similarly, global variables are tags, unless you specify
@samp{--no-globals}.  Use of @samp{--no-globals} and @samp{--no-defines}
can make the tags table file much smaller.

You can tag function declarations and external variables in addition
to function definitions by giving the @samp{--declarations} option to

In C++ code, in addition to all the tag constructs of C code, member
functions are also recognized, and optionally member variables if you
use the @samp{--members} option.  Tags for variables and functions in
classes are named @samp{@var{class}::@var{variable}} and
@samp{@var{class}::@var{function}}.  @code{operator} definitions have
tag names like @samp{operator+}.

In Java code, tags include all the constructs recognized in C++, plus
the @code{interface}, @code{extends} and @code{implements} constructs.
Tags for variables and functions in classes are named
@samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.

In La@TeX{} text, the argument of any of the commands @code{\chapter},
@code{\section}, @code{\subsection}, @code{\subsubsection},
252 253
@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite},
@code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry},
@code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand},
@code{\newenvironment} or @code{\renewenvironment} is a tag.@refill
256 257 258 259 260 261 262

Other commands can make tags as well, if you specify them in the
environment variable @env{TEXTAGS} before invoking @code{etags}.  The
value of this environment variable should be a colon-separated list of
command names.  For example,

264 265 266 267
export TEXTAGS
@end example

268 269
specifies (using Bourne shell syntax) that the commands
@samp{\mycommand} and @samp{\myothercommand} also define tags.
270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336

In Lisp code, any function defined with @code{defun}, any variable
defined with @code{defvar} or @code{defconst}, and in general the first
argument of any expression that starts with @samp{(def} in column zero, is
a tag.

In Scheme code, tags include anything defined with @code{def} or with a
construct whose name starts with @samp{def}.  They also include variables
set with @code{set!} at top level in the file.
@end itemize

  Several other languages are also supported:

@itemize @bullet

In Ada code, functions, procedures, packages, tasks, and types are
tags.  Use the @samp{--packages-only} option to create tags for
packages only.

In Ada, the same name can be used for different kinds of entity
(e.g.@:, for a procedure and for a function).  Also, for things like
packages, procedures and functions, there is the spec (i.e.@: the
interface) and the body (i.e.@: the implementation).  To make it
easier to pick the definition you want, Ada tag name have suffixes
indicating the type of entity:

@table @samp
@item /b
package body.
@item /f
@item /k
@item /p
@item /s
package spec.
@item /t
@end table

  Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
directly to the body of the package @code{bidule}, while @kbd{M-x
find-tag @key{RET} bidule @key{RET}} will just search for any tag

In assembler code, labels appearing at the beginning of a line,
followed by a colon, are tags.

In Bison or Yacc input files, each rule defines as a tag the nonterminal
it constructs.  The portions of the file that contain C code are parsed
as C code.

In Cobol code, tags are paragraph names; that is, any word starting in
column 8 and followed by a period.

In Erlang code, the tags are the functions, records, and macros defined
in the file.

Richard M. Stallman's avatar
Richard M. Stallman committed
In Fortran code, functions, subroutines and block data are tags.

Francesco Potortì's avatar
Francesco Potortì committed
339 340 341 342 343
In HTML input files, the tags are the @code{title} and the @code{h1},
@code{h2}, @code{h3} headers.  Also, tags are @code{name=} in anchors
and all occurrences of @code{id=}.

Francesco Potortì's avatar
Francesco Potortì committed
345 346
In makefiles, targets are tags; additionally, variables are tags
unless you specify @samp{--no-globals}.
347 348 349

In Objective C code, tags include Objective C definitions for classes,
Francesco Potortì's avatar
Francesco Potortì committed
350 351 352
class categories, methods, and protocols.  Tags for variables and
functions in classes are named @samp{@var{class}::@var{variable}} and
353 354 355 356 357 358

In Pascal code, the tags are the functions and procedures defined in
the file.

Francesco Potortì's avatar
Francesco Potortì committed
359 360 361 362 363 364
In Perl code, the tags are the packages, subroutines and variables
defined by the @code{package}, @code{sub}, @code{my} and @code{local}
keywords.  Use @samp{--globals} if you want to tag global variables.
Tags for subroutines are named @samp{@var{package}::@var{sub}}.  The
name for subroutines defined in the default package is

366 367 368 369
In PHP code, tags are functions, classes and defines.  When using the
@samp{--members} option, vars are tags too.

370 371 372 373
In PostScript code, the tags are the functions.

374 375
In Prolog code, tags are predicates and rules at the beginning of
376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418

In Python code, @code{def} or @code{class} at the beginning of a line
generate a tag.
@end itemize

  You can also generate tags based on regexp matching (@pxref{Etags
Regexps}) to handle other formats and languages.

@node Create Tags Table
@subsection Creating Tags Tables
@cindex @code{etags} program

  The @code{etags} program is used to create a tags table file.  It knows
the syntax of several languages, as described in
the previous section.
@end iftex
@ref{Tag Syntax}.
@end ifinfo
Here is how to run @code{etags}:

etags @var{inputfiles}@dots{}
@end example

The @code{etags} program reads the specified files, and writes a tags
table named @file{TAGS} in the current working directory.

  If the specified files don't exist, @code{etags} looks for
compressed versions of them and uncompresses them to read them.  Under
MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz}
if it is given @samp{mycode.c} on the command line and @file{mycode.c}
does not exist.

  @code{etags} recognizes the language used in an input file based on
its file name and contents.  You can specify the language with the
@samp{--language=@var{name}} option, described below.

  If the tags table data become outdated due to changes in the files
described in the table, the way to update the tags table is the same
419 420 421
way it was made in the first place.  If the tags table fails to record
a tag, or records it for the wrong file, then Emacs cannot possibly
find its definition until you update the tags table.  However, if the
position recorded in the tags table becomes a little bit wrong (due to
423 424 425 426
other editing), the only consequence is a slight delay in finding the
tag.  Even if the stored position is very far wrong, Emacs will still
find the tag, after searching most of the file for it.  Even that
delay is hardly noticeable with today's computers.
427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470

  So you should update a tags table when you define new tags that you want
to have listed, or when you move tag definitions from one file to another,
or when changes become substantial.  Normally there is no need to update
the tags table after each edit, or even every day.

  One tags table can virtually include another.  Specify the included
tags file name with the @samp{--include=@var{file}} option when
creating the file that is to include it.  The latter file then acts as
if it covered all the source files specified in the included file, as
well as the files it directly contains.

  If you specify the source files with relative file names when you run
@code{etags}, the tags file will contain file names relative to the
directory where the tags file was initially written.  This way, you can
move an entire directory tree containing both the tags file and the
source files, and the tags file will still refer correctly to the source

  If you specify absolute file names as arguments to @code{etags}, then
the tags file will contain absolute file names.  This way, the tags file
will still refer to the same files even if you move it, as long as the
source files remain in the same place.  Absolute file names start with
@samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.

  When you want to make a tags table from a great number of files, you
may have problems listing them on the command line, because some systems
have a limit on its length.  The simplest way to circumvent this limit
is to tell @code{etags} to read the file names from its standard input,
by typing a dash in place of the file names, like this:

find . -name "*.[chCH]" -print | etags -
@end smallexample

  Use the option @samp{--language=@var{name}} to specify the language
explicitly.  You can intermix these options with file names; each one
applies to the file names that follow it.  Specify
@samp{--language=auto} to tell @code{etags} to resume guessing the
language from the file names and file contents.  Specify
@samp{--language=none} to turn off language-specific processing
entirely; then @code{etags} recognizes tags by regexp matching alone
(@pxref{Etags Regexps}).

471 472 473 474 475 476
  The option @samp{--parse-stdin=@var{file}} is mostly useful when
calling @code{etags} from programs.  It can be used (only once) in
place of a file name on the command line.  @code{Etags} will read from
standard input and mark the produced tags as belonging to the file

477 478 479 480 481 482 483 484 485 486
  @samp{etags --help} prints the list of the languages @code{etags}
knows, and the file name rules for guessing the language.  It also prints
a list of all the available @code{etags} options, together with a short

@node Etags Regexps
@subsection Etags Regexps

  The @samp{--regex} option provides a general way of recognizing tags
based on regexp matching.  You can freely intermix it with file names.
487 488 489
If you specify multiple @samp{--regex} options, all of them are used
in parallel, but each one applies only to the source files that follow
it.  The syntax is:
490 491

492 493 494
@end smallexample

495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518
  The essential part of the option value is @var{tagregexp}, the
regexp for matching tags.  It is always used anchored, that is, it
only matches at the beginning of a line.  If you want to allow
indented tags, use a regexp that matches initial whitespace; start it
with @samp{[ \t]*}.

  In these regular expressions, @samp{\} quotes the next character, and
all the GCC character escape sequences are supported (@samp{\a} for
bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for
escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for
carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab).

  Ideally, @var{tagregexp} should not match more characters than are
needed to recognize what you want to tag.  If the syntax requires you
to write @var{tagregexp} so it matches more characters beyond the tag
itself, you should add a @var{nameregexp}, to pick out just the tag.
This will enable Emacs to find tags more accurately and to do
completion on tag names more reliably.  You can find some examples

  The @var{modifiers} are a sequence of zero or more characters that
modify the way @code{etags} does the matching.  A regexp with no
modifiers is applied sequentially to each line of the input file, in a
case-sensitive way.  The modifiers and their meanings are:
519 520 521

@table @samp
@item i
Ignore case when matching this regexp.
@item m
524 525
Match this regular expression against the whole file, so that
multi-line matches are possible.
@item s
527 528
Match this regular expression against the whole file, and allow
@samp{.} in @var{tagregexp} to match newlines.
529 530
@end table

  The @samp{-R} option cancels all the regexps defined by preceding
532 533 534 535
@samp{--regex} options.  It applies to the file names following it, as
you can see from the following example:

etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
537 538 539 540 541 542 543 544
    bar.ber -R --lang=lisp
@end smallexample

Here @code{etags} chooses the parsing language for @file{voo.doo} and
@file{bar.ber} according to their contents.  @code{etags} also uses
@var{reg1} to recognize additional tags in @file{voo.doo}, and both
@var{reg1} and @var{reg2} to recognize additional tags in
545 546 547 548
@file{bar.ber}.  @var{reg1} is checked against each line of
@file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while
@var{reg2} is checked against the whole @file{bar.ber} file,
permitting multi-line matches, in a case-sensitive way.  @code{etags}
549 550
uses only the Lisp tags rules, with no user-specified regexp matching,
to recognize tags in @file{}.

552 553
  You can restrict a @samp{--regex} option to match only files of a
given language by using the optional prefix @var{@{language@}}.
554 555 556
(@samp{etags --help} prints the list of languages recognized by
@code{etags}.)  This is particularly useful when storing many
predefined regular expressions for @code{etags} in a file.  The
557 558 559 560 561 562 563 564
following example tags the @code{DEFVAR} macros in the Emacs source
files, for the C language only:

--regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
@end smallexample

565 566 567 568
When you have complex regular expressions, you can store the list of
them in a file.  The following option syntax instructs @code{etags} to
read two files of regular expressions.  The regular expressions
contained in the second file are matched without regard to case.
569 570

--regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file}
572 573 574
@end smallexample

575 576 577 578 579 580 581 582 583
A regex file for @code{etags} contains one regular expression per
line.  Empty lines, and lines beginning with space or tab are ignored.
When the first character in a line is @samp{@@}, @code{etags} assumes
that the rest of the line is the name of another file of regular
expressions; thus, one such file can include another file.  All the
other lines are taken to be regular expressions.  If the first
non-whitespace text on the line is @samp{--}, that line is a comment.

  For example, we can create a file called @samp{emacs.tags} with the
584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885
following contents:

        -- This is for GNU Emacs C source files
@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
@end smallexample

and then use it like this:

etags --regex=@@emacs.tags *.[ch] */*.[ch]
@end smallexample

  Here are some more examples.  The regexps are quoted to protect them
from shell interpretation.

@itemize @bullet

Tag Octave files:

etags --language=none \
      --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
      --regex='/###key \(.*\)/\1/' \
      --regex='/[ \t]*global[ \t].*/' \
@end smallexample

Note that tags are not generated for scripts, so that you have to add
a line by yourself of the form @samp{###key @var{scriptname}} if you
want to jump to it.

Tag Tcl files:

etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
@end smallexample

Tag VHDL files:

etags --language=none \
  --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
  \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
@end smallexample
@end itemize

@node Select Tags Table
@subsection Selecting a Tags Table

@vindex tags-file-name
@findex visit-tags-table
  Emacs has at any time one @dfn{selected} tags table, and all the commands
for working with tags tables use the selected one.  To select a tags table,
type @kbd{M-x visit-tags-table}, which reads the tags table file name as an
argument.  The name @file{TAGS} in the default directory is used as the
default file name.

  All this command does is store the file name in the variable
@code{tags-file-name}.  Emacs does not actually read in the tags table
contents until you try to use them.  Setting this variable yourself is just
as good as using @code{visit-tags-table}.  The variable's initial value is
@code{nil}; that value tells all the commands for working with tags tables
that they must ask for a tags table file name to use.

  Using @code{visit-tags-table} when a tags table is already loaded
gives you a choice: you can add the new tags table to the current list
of tags tables, or start a new list.  The tags commands use all the tags
tables in the current list.  If you start a new list, the new tags table
is used @emph{instead} of others.  If you add the new table to the
current list, it is used @emph{as well as} the others.  When the tags
commands scan the list of tags tables, they don't always start at the
beginning of the list; they start with the first tags table (if any)
that describes the current file, proceed from there to the end of the
list, and then scan from the beginning of the list until they have
covered all the tables in the list.

@vindex tags-table-list
  You can specify a precise list of tags tables by setting the variable
@code{tags-table-list} to a list of strings, like this:

@c keep this on two lines for formatting in smallbook
(setq tags-table-list
      '("~/emacs" "/usr/local/lib/emacs/src"))
@end group
@end example

This tells the tags commands to look at the @file{TAGS} files in your
@file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
directory.  The order depends on which file you are in and which tags
table mentions that file, as explained above.

  Do not set both @code{tags-file-name} and @code{tags-table-list}.

@node Find Tag
@subsection Finding a Tag

  The most important thing that a tags table enables you to do is to find
the definition of a specific tag.

@table @kbd
@item M-.@: @var{tag} @key{RET}
Find first definition of @var{tag} (@code{find-tag}).
@item C-u M-.
Find next alternate definition of last tag specified.
@item C-u - M-.
Go back to previous tag found.
@item C-M-. @var{pattern} @key{RET}
Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
@item C-u C-M-.
Find the next tag whose name matches the last pattern used.
@item C-x 4 .@: @var{tag} @key{RET}
Find first definition of @var{tag}, but display it in another window
@item C-x 5 .@: @var{tag} @key{RET}
Find first definition of @var{tag}, and create a new frame to select the
buffer (@code{find-tag-other-frame}).
@item M-*
Pop back to where you previously invoked @kbd{M-.} and friends.
@end table

@kindex M-.
@findex find-tag
  @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
a specified tag.  It searches through the tags table for that tag, as a
string, and then uses the tags table info to determine the file that the
definition is in and the approximate character position in the file of
the definition.  Then @code{find-tag} visits that file, moves point to
the approximate character position, and searches ever-increasing
distances away to find the tag definition.

  If an empty argument is given (just type @key{RET}), the balanced
expression in the buffer before or around point is used as the
@var{tag} argument.  @xref{Expressions}.

  You don't need to give @kbd{M-.} the full name of the tag; a part
will do.  This is because @kbd{M-.} finds tags in the table which
contain @var{tag} as a substring.  However, it prefers an exact match
to a substring match.  To find other tags that match the same
substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
M-.}; this does not read a tag name, but continues searching the tags
table's text for another tag containing the same substring last used.
If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier
alternative to @kbd{C-u M-.}.

@kindex C-x 4 .
@findex find-tag-other-window
@kindex C-x 5 .
@findex find-tag-other-frame
  Like most commands that can switch buffers, @code{find-tag} has a
variant that displays the new buffer in another window, and one that
makes a new frame for it.  The former is @kbd{C-x 4 .}, which invokes
the command @code{find-tag-other-window}.  The latter is @kbd{C-x 5 .},
which invokes @code{find-tag-other-frame}.

  To move back to places you've found tags recently, use @kbd{C-u -
M-.}; more generally, @kbd{M-.} with a negative numeric argument.  This
command can take you to another buffer.  @kbd{C-x 4 .} with a negative
argument finds the previous tag location in another window.

@kindex M-*
@findex pop-tag-mark
@vindex find-tag-marker-ring-length
  As well as going back to places you've found tags recently, you can go
back to places @emph{from where} you found them.  Use @kbd{M-*}, which
invokes the command @code{pop-tag-mark}, for this.  Typically you would
find and study the definition of something with @kbd{M-.} and then
return to where you were with @kbd{M-*}.

  Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
a depth determined by the variable @code{find-tag-marker-ring-length}.

@findex find-tag-regexp
@kindex C-M-.
  The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
match a specified regular expression.  It is just like @kbd{M-.} except
that it does regexp matching instead of substring matching.

@node Tags Search
@subsection Searching and Replacing with Tags Tables
@cindex search and replace in multiple files
@cindex multiple-file search and replace

  The commands in this section visit and search all the files listed in the
selected tags table, one by one.  For these commands, the tags table serves
only to specify a sequence of files to search.

@table @kbd
@item M-x tags-search @key{RET} @var{regexp} @key{RET}
Search for @var{regexp} through the files in the selected tags
@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
Perform a @code{query-replace-regexp} on each file in the selected tags table.
@item M-,
Restart one of the commands above, from the current location of point
@end table

@findex tags-search
  @kbd{M-x tags-search} reads a regexp using the minibuffer, then
searches for matches in all the files in the selected tags table, one
file at a time.  It displays the name of the file being searched so you
can follow its progress.  As soon as it finds an occurrence,
@code{tags-search} returns.

@kindex M-,
@findex tags-loop-continue
  Having found one match, you probably want to find all the rest.  To find
one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
@code{tags-search}.  This searches the rest of the current buffer, followed
by the remaining files of the tags table.@refill

@findex tags-query-replace
  @kbd{M-x tags-query-replace} performs a single
@code{query-replace-regexp} through all the files in the tags table.  It
reads a regexp to search for and a string to replace with, just like
ordinary @kbd{M-x query-replace-regexp}.  It searches much like @kbd{M-x
tags-search}, but repeatedly, processing matches according to your
input.  @xref{Replace}, for more information on query replace.

@vindex tags-case-fold-search
@cindex case-sensitivity and tags search
  You can control the case-sensitivity of tags search commands by
customizing the value of the variable @code{tags-case-fold-search}.  The
default is to use the same setting as the value of
@code{case-fold-search} (@pxref{Search Case}).

  It is possible to get through all the files in the tags table with a
single invocation of @kbd{M-x tags-query-replace}.  But often it is
useful to exit temporarily, which you can do with any input event that
has no special query replace meaning.  You can resume the query replace
subsequently by typing @kbd{M-,}; this command resumes the last tags
search or replace command that you did.

  The commands in this section carry out much broader searches than the
@code{find-tag} family.  The @code{find-tag} commands search only for
definitions of tags that match your substring or regexp.  The commands
@code{tags-search} and @code{tags-query-replace} find every occurrence
of the regexp, as ordinary search commands and replace commands do in
the current buffer.

  These commands create buffers only temporarily for the files that they
have to search (those which are not already visited in Emacs buffers).
Buffers in which no match is found are quickly killed; the others
continue to exist.

  It may have struck you that @code{tags-search} is a lot like
@code{grep}.  You can also run @code{grep} itself as an inferior of
Emacs and have Emacs show you the matching lines one by one.  This works
much like running a compilation; finding the source locations of the
@code{grep} matches works like finding the compilation errors.

@node List Tags
@subsection Tags Table Inquiries

@table @kbd
@item M-x list-tags @key{RET} @var{file} @key{RET}
Display a list of the tags defined in the program file @var{file}.
@item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
Display a list of all tags matching @var{regexp}.
@end table

@findex list-tags
  @kbd{M-x list-tags} reads the name of one of the files described by
the selected tags table, and displays a list of all the tags defined in
that file.  The ``file name'' argument is really just a string to
compare against the file names recorded in the tags table; it is read as
a string rather than as a file name.  Therefore, completion and
defaulting are not available, and you must enter the file name the same
way it appears in the tags table.  Do not include a directory as part of
the file name unless the file name recorded in the tags table includes a

@findex tags-apropos
@vindex tags-apropos-verbose
  @kbd{M-x tags-apropos} is like @code{apropos} for tags
(@pxref{Apropos}).  It finds all the tags in the selected tags table
whose entries match @var{regexp}, and displays them.  If the variable
@code{tags-apropos-verbose} is non-@code{nil}, it displays the names
of the tags files together with the tag names.

@vindex tags-tag-face
@vindex tags-apropos-additional-actions
You can customize the appearance of the output with the face
@code{tags-tag-face}.  You can display additional output with @kbd{M-x
tags-apropos} by customizing the variable
@code{tags-apropos-additional-actions}---see its documentation for

  You can also use the collection of tag names to complete a symbol
name in the buffer.  @xref{Symbol Completion}.

@node Emerge
887 888 889 890 891 892 893 894
@section Merging Files with Emerge
@cindex Emerge
@cindex merging files

It's not unusual for programmers to get their signals crossed and modify
the same program in two different directions.  To recover from this
confusion, you need to merge the two versions.  Emerge makes this
easier.  See also @ref{Comparing Files}, for commands to compare
in a more manual fashion, and @ref{Top, Ediff,, ediff, The Ediff Manual}.
896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272

* Overview of Emerge::	How to start Emerge.  Basic concepts.
* Submodes of Emerge::	Fast mode vs. Edit mode.
			  Skip Prefers mode and Auto Advance mode.
* State of Difference::	You do the merge by specifying state A or B
			  for each difference.
* Merge Commands::	Commands for selecting a difference,
			  changing states of differences, etc.
* Exiting Emerge::	What to do when you've finished the merge.
* Combining in Emerge::	    How to keep both alternatives for a difference.
* Fine Points of Emerge::   Misc.
@end menu

@node Overview of Emerge
@subsection Overview of Emerge

To start Emerge, run one of these four commands:

@table @kbd
@item M-x emerge-files
@findex emerge-files
Merge two specified files.

@item M-x emerge-files-with-ancestor
@findex emerge-files-with-ancestor
Merge two specified files, with reference to a common ancestor.

@item M-x emerge-buffers
@findex emerge-buffers
Merge two buffers.

@item M-x emerge-buffers-with-ancestor
@findex emerge-buffers-with-ancestor
Merge two buffers with reference to a common ancestor in a third
@end table

@cindex merge buffer (Emerge)
@cindex A and B buffers (Emerge)
  The Emerge commands compare two files or buffers, and display the
comparison in three buffers: one for each input text (the @dfn{A buffer}
and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging
takes place.  The merge buffer shows the full merged text, not just the
differences.  Wherever the two input texts differ, you can choose which
one of them to include in the merge buffer.

  The Emerge commands that take input from existing buffers use only the
accessible portions of those buffers, if they are narrowed

  If a common ancestor version is available, from which the two texts to
be merged were both derived, Emerge can use it to guess which
alternative is right.  Wherever one current version agrees with the
ancestor, Emerge presumes that the other current version is a deliberate
change which should be kept in the merged version.  Use the
@samp{with-ancestor} commands if you want to specify a common ancestor
text.  These commands read three file or buffer names---variant A,
variant B, and the common ancestor.

  After the comparison is done and the buffers are prepared, the
interactive merging starts.  You control the merging by typing special
@dfn{merge commands} in the merge buffer.  The merge buffer shows you a
full merged text, not just differences.  For each run of differences
between the input texts, you can choose which one of them to keep, or
edit them both together.

  The merge buffer uses a special major mode, Emerge mode, with commands
for making these choices.  But you can also edit the buffer with
ordinary Emacs commands.

  At any given time, the attention of Emerge is focused on one
particular difference, called the @dfn{selected} difference.  This
difference is marked off in the three buffers like this:

@var{text that differs}
@end example

Emerge numbers all the differences sequentially and the mode
line always shows the number of the selected difference.

  Normally, the merge buffer starts out with the A version of the text.
But when the A version of a difference agrees with the common ancestor,
then the B version is initially preferred for that difference.

  Emerge leaves the merged text in the merge buffer when you exit.  At
that point, you can save it in a file with @kbd{C-x C-w}.  If you give a
numeric argument to @code{emerge-files} or
@code{emerge-files-with-ancestor}, it reads the name of the output file
using the minibuffer.  (This is the last file name those commands read.)
Then exiting from Emerge saves the merged text in the output file.

  Normally, Emerge commands save the output buffer in its file when you
exit.  If you abort Emerge with @kbd{C-]}, the Emerge command does not
save the output buffer, but you can save it yourself if you wish.

@node Submodes of Emerge
@subsection Submodes of Emerge

  You can choose between two modes for giving merge commands: Fast mode
and Edit mode.  In Fast mode, basic merge commands are single
characters, but ordinary Emacs commands are disabled.  This is
convenient if you use only merge commands.  In Edit mode, all merge
commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs
commands are also available.  This allows editing the merge buffer, but
slows down Emerge operations.

  Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to
Fast mode.  The mode line indicates Edit and Fast modes with @samp{E}
and @samp{F}.

  Emerge has two additional submodes that affect how particular merge
commands work: Auto Advance mode and Skip Prefers mode.

  If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands
advance to the next difference.  This lets you go through the merge
faster as long as you simply choose one of the alternatives from the
input.  The mode line indicates Auto Advance mode with @samp{A}.

  If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands
skip over differences in states prefer-A and prefer-B (@pxref{State of
Difference}).  Thus you see only differences for which neither version
is presumed ``correct.''  The mode line indicates Skip Prefers mode with

@findex emerge-auto-advance-mode
@findex emerge-skip-prefers-mode
  Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or
clear Auto Advance mode.  Use @kbd{s s}
(@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode.
These commands turn on the mode with a positive argument, turns it off
with a negative or zero argument, and toggle the mode with no argument.

@node State of Difference
@subsection State of a Difference

  In the merge buffer, a difference is marked with lines of @samp{v} and
@samp{^} characters.  Each difference has one of these seven states:

@table @asis
@item A
The difference is showing the A version.  The @kbd{a} command always
produces this state; the mode line indicates it with @samp{A}.

@item B
The difference is showing the B version.  The @kbd{b} command always
produces this state; the mode line indicates it with @samp{B}.

@item default-A
@itemx default-B
The difference is showing the A or the B state by default, because you
haven't made a choice.  All differences start in the default-A state
(and thus the merge buffer is a copy of the A buffer), except those for
which one alternative is ``preferred'' (see below).

When you select a difference, its state changes from default-A or
default-B to plain A or B.  Thus, the selected difference never has
state default-A or default-B, and these states are never displayed in
the mode line.

The command @kbd{d a} chooses default-A as the default state, and @kbd{d
b} chooses default-B.  This chosen default applies to all differences
which you haven't ever selected and for which no alternative is preferred.
If you are moving through the merge sequentially, the differences you
haven't selected are those following the selected one.  Thus, while
moving sequentially, you can effectively make the A version the default
for some sections of the merge buffer and the B version the default for
others by using @kbd{d a} and @kbd{d b} between sections.

@item prefer-A
@itemx prefer-B
The difference is showing the A or B state because it is
@dfn{preferred}.  This means that you haven't made an explicit choice,
but one alternative seems likely to be right because the other
alternative agrees with the common ancestor.  Thus, where the A buffer
agrees with the common ancestor, the B version is preferred, because
chances are it is the one that was actually changed.

These two states are displayed in the mode line as @samp{A*} and @samp{B*}.

@item combined
The difference is showing a combination of the A and B states, as a
result of the @kbd{x c} or @kbd{x C} commands.

Once a difference is in this state, the @kbd{a} and @kbd{b} commands
don't do anything to it unless you give them a numeric argument.

The mode line displays this state as @samp{comb}.
@end table

@node Merge Commands
@subsection Merge Commands

  Here are the Merge commands for Fast mode; in Edit mode, precede them
with @kbd{C-c C-c}:

@table @kbd
@item p
Select the previous difference.

@item n
Select the next difference.

@item a
Choose the A version of this difference.

@item b
Choose the B version of this difference.

@item C-u @var{n} j
Select difference number @var{n}.

@item .
Select the difference containing point.  You can use this command in the
merge buffer or in the A or B buffer.

@item q
Quit---finish the merge.

@item C-]
Abort---exit merging and do not save the output.

@item f
Go into Fast mode.  (In Edit mode, this is actually @kbd{C-c C-c f}.)

@item e
Go into Edit mode.

@item l
Recenter (like @kbd{C-l}) all three windows.

@item -
Specify part of a prefix numeric argument.

@item @var{digit}
Also specify part of a prefix numeric argument.

@item d a
Choose the A version as the default from here down in
the merge buffer.

@item d b
Choose the B version as the default from here down in
the merge buffer.

@item c a
Copy the A version of this difference into the kill ring.

@item c b
Copy the B version of this difference into the kill ring.

@item i a
Insert the A version of this difference at point.

@item i b
Insert the B version of this difference at point.

@item m
Put point and mark around the difference.

@item ^
Scroll all three windows down (like @kbd{M-v}).

@item v
Scroll all three windows up (like @kbd{C-v}).

@item <
Scroll all three windows left (like @kbd{C-x <}).

@item >
Scroll all three windows right (like @kbd{C-x >}).

@item |
Reset horizontal scroll on all three windows.

@item x 1
Shrink the merge window to one line.  (Use @kbd{C-u l} to restore it
to full size.)

@item x c
Combine the two versions of this difference (@pxref{Combining in

@item x f
Show the names of the files/buffers Emerge is operating on, in a Help
window.  (Use @kbd{C-u l} to restore windows.)

@item x j
Join this difference with the following one.
(@kbd{C-u x j} joins this difference with the previous one.)

@item x s
Split this difference into two differences.  Before you use this
command, position point in each of the three buffers at the place where
you want to split the difference.

@item x t
Trim identical lines off the top and bottom of the difference.
Such lines occur when the A and B versions are
identical but differ from the ancestor version.
@end table

@node Exiting Emerge
@subsection Exiting Emerge

  The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing
the results into the output file if you specified one.  It restores the
A and B buffers to their proper contents, or kills them if they were
created by Emerge and you haven't changed them.  It also disables the
Emerge commands in the merge buffer, since executing them later could
damage the contents of the various buffers.

  @kbd{C-]} aborts the merge.  This means exiting without writing the
output file.  If you didn't specify an output file, then there is no
real difference between aborting and finishing the merge.

  If the Emerge command was called from another Lisp program, then its
return value is @code{t} for successful completion, or @code{nil} if you

@node Combining in Emerge
@subsection Combining the Two Versions

  Sometimes you want to keep @emph{both} alternatives for a particular
difference.  To do this, use @kbd{x c}, which edits the merge buffer
like this:

#ifdef NEW
@var{version from A buffer}
#else /* not NEW */
@var{version from B buffer}
#endif /* not NEW */
@end group
@end example

@vindex emerge-combine-versions-template
While this example shows C preprocessor conditionals delimiting the two
alternative versions, you can specify the strings to use by setting
the variable @code{emerge-combine-versions-template} to a string of your
choice.  In the string, @samp{%a} says where to put version A, and
@samp{%b} says where to put version B.  The default setting, which
produces the results shown above, looks like this:

"#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n"
@end group
@end example

@node Fine Points of Emerge
@subsection Fine Points of Emerge

  During the merge, you mustn't try to edit the A and B buffers yourself.
Emerge modifies them temporarily, but ultimately puts them back the way
they were.

  You can have any number of merges going at once---just don't use any one
buffer as input to more than one merge at once, since the temporary
changes made in these buffers would get in each other's way.

  Starting Emerge can take a long time because it needs to compare the
files fully.  Emacs can't do anything else until @code{diff} finishes.
Perhaps in the future someone will change Emerge to do the comparison in
the background when the input files are large---then you could keep on
doing other things with Emacs until Emerge is ready to accept

@vindex emerge-startup-hook
  After setting up the merge, Emerge runs the hook
@code{emerge-startup-hook} (@pxref{Hooks}).