1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
3 @c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
4 @c Free Software Foundation, Inc.
5 @c See file emacs.texi for copying conditions.
6 @node Maintaining, Abbrevs, Building, Top
7 @chapter Maintaining Large Programs
9 This chapter describes Emacs features for maintaining large
13 * Version Control:: Using version control systems.
14 * Change Log:: Maintaining a change history for your program.
15 * Tags:: Go directly to any function in your program in one
16 command. Tags remembers which file it is in.
18 * Emerge:: A convenient way of merging two versions of a program.
23 @section Version Control
24 @cindex version control
26 A @dfn{version control system} is a package that can record multiple
27 versions of a source file, storing information such as the creation
28 time of each version, who created it, and a description of what was
29 changed in that version.
31 The Emacs version control interface is called VC. Its commands work
32 with several different version control systems; currently, it supports
33 GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS, SCCS/CSSC, and
34 Subversion. Of these, the GNU project distributes CVS, GNU Arch, RCS,
37 VC is enabled automatically whenever you visit a file that is
38 governed by a version control system. To disable VC entirely, set the
39 customizable variable @code{vc-handled-backends} to @code{nil}
41 (@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
44 (@pxref{Customizing VC}).
48 * Introduction to VC:: How version control works in general.
49 * VC Mode Line:: How the mode line shows version control status.
50 * Basic VC Editing:: How to edit a file under version control.
51 * Old Revisions:: Examining and comparing old versions.
52 * Secondary VC Commands:: The commands used a little less frequently.
53 * VC Directory Mode:: Listing files managed by version control.
54 * Branches:: Multiple lines of development.
56 * Remote Repositories:: Efficient access to remote CVS servers.
57 * Revision Tags:: Symbolic names for revisions.
58 * Miscellaneous VC:: Various other commands and features of VC.
59 * Customizing VC:: Variables that change VC's behavior.
63 @node Introduction to VC
64 @subsection Introduction to Version Control
66 VC allows you to use a version control system from within Emacs,
67 integrating the version control operations smoothly with editing.
68 Though VC cannot completely bridge the gaps between version control
69 systems with widely differing capabilities, it does provide a uniform
70 interface to many version control operations. Regardless of which
71 version control system is in use, you will be able to do basic
72 operations in much the same way.
74 This section provides a general overview of version control, and
75 describes the version control systems that VC supports. You can skip
76 this section if you are already familiar with the version control system
80 * Why Version Control?:: Understanding the problems it addresses.
81 * Version Control Systems:: Supported version control back-end systems.
82 * VCS Concepts:: Words and concepts related to version control.
83 * Types of Log File:: The VCS log in contrast to the ChangeLog.
86 @node Why Version Control?
87 @subsubsection Understanding the problems it addresses
89 Version control systems provide you with three important
94 @dfn{Reversibility}: the ability to back up to a previous state if you
95 discover that some modification you did was a mistake or a bad idea.
98 @dfn{Concurrency}: the ability to have many people modifying the same
99 collection of files knowing that conflicting modifications can be
100 detected and resolved.
103 @dfn{History}: the ability to attach historical data to your data,
104 such as explanatory comments about the intention behind each change to
105 it. Even for a programmer working solo, change histories are an
106 important aid to memory; for a multi-person project, they are a
107 vitally important form of communication among developers.
110 @node Version Control Systems
111 @subsubsection Supported Version Control Systems
113 @cindex back end (version control)
114 VC currently works with many different version control systems or
121 SCCS was the first version control system ever built, and was long ago
122 superseded by more advanced ones. VC compensates for certain features
123 missing in SCCS (e.g., tag names for releases) by implementing them
124 itself. Other VC features, such as multiple branches, are simply
125 unavailable. Since SCCS is non-free, we recommend avoiding it.
129 CSSC is a free replacement for SCCS. You should use CSSC only if, for
130 some reason, you cannot use a more recent and better-designed version
135 RCS is the free version control system around which VC was initially
136 built. Almost everything you can do with RCS can be done through VC.
137 However, you cannot use RCS over the network, and it only works at the
138 level of individual files rather than projects.
142 CVS is the free version control system that was, until recently (circa
143 2008), used by the majority of free software projects. Nowadays, it
144 is slowly being superseded by newer systems. CVS allows concurrent
145 multi-user development either locally or over the network. It lacks
146 support for atomic commits or file moving/renaming. VC supports all
147 basic editing operations under CVS. For some less common tasks, you
148 still need to call CVS from the command line. Note also that before
149 using CVS you must set up a repository, which is a subject too complex
155 Subversion (SVN) is a free version control system designed to be
156 similar to CVS but without its problems. It supports atomic commits
157 of filesets, and versioning of directories, symbolic links, meta-data,
158 renames, copies, and deletes.
163 GNU Arch is a version control system designed for distributed work.
164 It differs in many ways from older systems like CVS and RCS. It
165 provides different methods for interoperating between users, support
166 for offline operations, and good branching and merging features. It
167 also supports atomic commits of filesets and file moving/renaming. VC
168 does not support all operations provided by GNU Arch, so you must
169 sometimes invoke it from the command line.
173 Git is a distributed version control system invented by Linus Torvalds to support
174 development of Linux (his kernel). It supports atomic commits of filesets and
175 file moving/renaming. One significant feature of git is that it
176 largely abolishes the notion of a single centralized repository;
177 instead, each working copy of a git project is its own repository and
178 coordination is done through repository-sync operations. VC supports
179 most git operations, with the exception of news merges and repository
180 syncing; these must be done from the command line.
185 Mercurial (hg) is a distributed version control system broadly
186 resembling GNU Arch and git, with atomic fileset commits and file
187 moving/renaming. Like git, it is fully decentralized. VC supports
188 most Mercurial commands, with the exception of repository sync
189 operations; this needs to be done from the command line.
194 Bazaar (bzr) is a distributed version control system that supports both
195 repository-based and distributed versioning, with atomic fileset
196 commits and file moving/renaming. VC supports most basic editing
197 operations under Bazaar.
200 Previous versions of VC supported a version control system known as
201 Meta-CVS. This support has been dropped because of limited interest
202 from users and developers.
205 @subsubsection Concepts of Version Control
208 @cindex registered file
209 When a file is under version control, we say that it is
210 @dfn{registered} in the version control system. The system has a
211 @dfn{repository} which stores both the file's present state and its
212 change history---enough to reconstruct the current version or any
213 earlier version. The repository also contains other information, such
214 as @dfn{log entries} that describe the changes made to each file.
217 @cindex checking out files
218 A file @dfn{checked out} of a repository is called the @dfn{work
219 file}. You edit the work file and make changes in it, as you would
220 with an ordinary file. After you are done with a set of changes, you
221 @dfn{check in} or @dfn{commit} the file; this records the changes in
222 the repository, along with a log entry for those changes.
226 A copy of a file stored in a repository is called a @dfn{revision}.
227 The history of a file is a sequence of revisions. Each revision is
228 named by a @dfn{revision ID}. The format of the revision ID depends
229 on the version control system; in the simplest case, it is just an
232 To go beyond these basic concepts, you will need to understand three
233 aspects in which version control systems differ.
234 They can be locking-based or merging-based; they can be file-based or
235 changeset-based; and they can be centralized or decentralized. VC
236 handles all these modes of operation, but it cannot hide the differences.
238 @cindex locking versus merging
239 A version control system typically has some mechanism to coordinate
240 between users who want to change the same file. There are two ways to
241 do this: merging and locking.
243 In a version control system that uses merging, each user may check
244 out and modify a work file at any time. The system lets you
245 @dfn{merge} your work file, which may contain changes that have not
246 been checked in, with the latest changes that others have checked into
249 Older version control systems use a @dfn{locking} scheme instead.
250 Here, work files are normally read-only. To edit a file, you ask the
251 version control system to make it writable for you by @dfn{locking}
252 it; only one user can lock a given file at any given time. This
253 procedure is analogous to, but different from, the locking that Emacs
254 uses to detect simultaneous editing of ordinary files
255 (@pxref{Interlocking}). When you check in your changes, that unlocks
256 the file, and the work file becomes read-only again. Other users may
257 then lock the file to make their own changes.
259 Both locking and merging systems can have problems when multiple
260 users try to modify the same file at the same time. Locking systems
261 have @dfn{lock conflicts}; a user may try to check a file out and be
262 unable to because it is locked. In merging systems, @dfn{merge
263 conflicts} happen when you check in a change to a file that conflicts
264 with a change checked in by someone else after your checkout. Both
265 kinds of conflict have to be resolved by human judgment and
266 communication. Experience has shown that merging is superior to
267 locking, both in convenience to developers and in minimizing the
268 number and severity of conflicts that actually occur.
270 SCCS always uses locking. RCS is lock-based by default but can be
271 told to operate in a merging style. CVS and Subversion are
272 merge-based by default but can be told to operate in a locking mode.
273 Distributed version control systems, such as GNU Arch, git, and
274 Mercurial, are exclusively merging-based.
276 VC mode supports both locking and merging version control. The
277 terms ``checkin'' and ``checkout'' come from locking-based version
278 control systems; newer version control systems have slightly different
279 operations usually called ``commit'' and ``update'', but VC hides the
280 differences between them as much as possible.
282 @cindex files versus changesets.
283 On SCCS, RCS, CVS, and other early version control systems, version
284 control operations are @dfn{file-based}: each file has its own comment
285 and revision history separate from that of all other files in the
286 system. Later systems, beginning with Subversion, are
287 @dfn{changeset-based}: a checkin may include changes to several files,
288 and the entire set of changes is treated as a unit by the system. Any
289 comment associated with the change does not belong to a single file,
290 but to the changeset itself.
292 Changeset-based version control is more flexible and powerful than
293 file-based version control; usually, when a change to multiple files
294 has to be reversed, it's good to be able to easily identify and remove
297 @cindex centralized vs. decentralized version control
298 Early version control systems were designed around a
299 @dfn{centralized} model in which each project has only one repository
300 used by all developers. SCCS, RCS, CVS, and Subversion share this
301 kind of model. One of its drawbacks is that the repository is a choke
302 point for reliability and efficiency.
304 GNU Arch pioneered the concept of @dfn{decentralized} version
305 control, later implemented in git, Mercurial, and Bazaar. A project
306 may have several different repositories, and these systems support a
307 sort of super-merge between repositories that tries to reconcile their
308 change histories. At the limit, each developer has his/her own
309 repository, and repository merges replace checkin/commit operations.
311 VC's job is to help you manage the traffic between your personal
312 workfiles and a repository. Whether that repository is a single
313 master or one of a network of peer repositories is not something VC
314 has to care about. Thus, the difference between a centralized and a
315 decentralized version control system is invisible to VC mode.
317 @node Types of Log File
318 @subsubsection Types of Log File
319 @cindex types of log file
320 @cindex log File, types of
321 @cindex version control log
323 Projects that use a version control system can have two types of log
324 for changes. One is the log maintained by the version control system:
325 each time you check in a change, you fill out a @dfn{log entry} for
326 the change (@pxref{Log Buffer}). This is called the @dfn{version
329 The other kind of log is the file @file{ChangeLog} (@pxref{Change
330 Log}). It provides a chronological record of all changes to a large
331 portion of a program---typically one directory and its subdirectories.
332 A small program would use one @file{ChangeLog} file; a large program
333 may have a @file{ChangeLog} file in each major directory.
334 @xref{Change Log}. Programmers have used change logs since long
335 before version control systems.
337 Changeset-based version systems typically maintain a changeset-based
338 modification log for the entire system, which makes change log files
339 somewhat redundant. One advantage that they retain is that it is
340 sometimes useful to be able to view the transaction history of a
341 single directory separately from those of other directories.
343 A project maintained with version control can use just the version
344 control log, or it can use both kinds of logs. It can handle some
345 files one way and some files the other way. Each project has its
346 policy, which you should follow.
348 When the policy is to use both, you typically want to write an entry
349 for each change just once, then put it into both logs. You can write
350 the entry in @file{ChangeLog}, then copy it to the log buffer with
351 @kbd{C-c C-a} when checking in the change (@pxref{Log Buffer}). Or
352 you can write the entry in the log buffer while checking in the
353 change, and later use the @kbd{C-x v a} command to copy it to
356 (@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
359 (@pxref{Change Logs and VC}).
363 @subsection Version Control and the Mode Line
365 When you visit a file that is under version control, Emacs indicates
366 this on the mode line. For example, @samp{RCS-1.3} says that RCS is
367 used for that file, and the current version is 1.3.
369 The character between the back-end name and the revision ID
370 indicates the version control status of the file. @samp{-} means that
371 the work file is not locked (if locking is in use), or not modified (if
372 locking is not in use). @samp{:} indicates that the file is locked, or
373 that it is modified. If the file is locked by some other user (for
374 instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
376 On a graphical display, you can move the mouse over this mode line
377 indicator to pop up a ``tool-tip'', which displays a more verbose
378 description of the version control status. Pressing @kbd{Mouse-1}
379 over the indicator pops up a menu of VC commands. This menu is
380 identical to the @samp{Tools / Version Control} menu item.
382 @vindex auto-revert-check-vc-info
383 When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is
384 under version control, it updates the version control information in
385 the mode line. However, Auto Revert mode may not properly update this
386 information if the version control status changes without changes to
387 the work file, from outside the current Emacs session. If you set
388 @code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates
389 the version control status information every
390 @code{auto-revert-interval} seconds, even if the work file itself is
391 unchanged. The resulting CPU usage depends on the version control
392 system, but is usually not excessive.
394 @node Basic VC Editing
395 @subsection Basic Editing under Version Control
398 Most VC commands operate on @dfn{VC filesets}. A VC fileset is a
399 collection of one or more files that a VC operation acts on. When you
400 type VC commands in a buffer visiting a version-controlled file, the
401 VC fileset is simply that one file. When you type them in a VC
402 Directory buffer, and some files in it are marked, the VC fileset
403 consists of the marked files (@pxref{VC Directory Mode}).
405 The principal VC command is an all-purpose command, @kbd{C-x v v}
406 (@code{vc-next-action}), that performs either registration, locking,
407 merging or a check-in (depending on the situation) on the current VC
408 fileset. You can use @kbd{C-x v v} in a file-visiting buffer or in a
413 Perform the appropriate next version control operation on the VC fileset.
416 @findex vc-next-action
418 The precise action of @kbd{C-x v v} depends on the state of the VC
419 fileset, and whether the version control system uses locking or
420 merging. This is described in detail in the subsequent sections.
422 VC filesets are the way that VC mode bridges the gap between
423 file-based and changeset-based version control systems. They are,
424 essentially, a way to pass multiple file arguments as a group to
425 version control commands. For example, on Subversion, a checkin with
426 a multi-file VC fileset becomes a joint commit, as though you had
427 typed @command{svn commit} with those file arguments at the shell
428 command line. All files in a VC fileset must be under the same
429 version control system; if they are not, Emacs signals an error when
430 you attempt to execute a command on the fileset.
432 Support for VC filesets and changeset-based version control systems
433 is the main improvement to VC in Emacs 23. When you mark multi-file
434 VC in a VC Directory buffer, VC operations treat them as a VC fileset,
435 and operate on them all at once if the version control system is
436 changeset-based. @xref{VC Directory Mode}.
438 VC filesets are distinct from the ``named filesets'' used for
439 viewing and visiting files in functional groups (@pxref{Filesets}).
440 Unlike named filesets, VC filesets are not named and don't persist
444 * VC With A Merging VCS:: Without locking: default mode for CVS.
445 * VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS.
446 * Advanced C-x v v:: Advanced features available with a prefix argument.
447 * Log Buffer:: Features available in log entry buffers.
450 @node VC With A Merging VCS
451 @subsubsection Basic Version Control with Merging
453 When your version control system is merging-based (the default for
454 CVS and all newer version control systems), work files are always
455 writable; you need not do anything special to begin editing a file.
456 The status indicator on the mode line is @samp{-} if the file is
457 unmodified; it flips to @samp{:} as soon as you save any changes
458 (@pxref{VC Mode Line}).
460 Here is what @kbd{C-x v v} does when using a merging-based system:
464 If the work file is in a directory that is not controlled by any
465 version control system, prompt for a repository type. Then, create a
466 version control repository of that type and register the file with it.
469 If the work file is in a directory that is controlled by a version
470 control system but not registered with it, register the file.
473 If the work file is the same as in the repository, do nothing.
476 If you have not changed the work file, but some other user has checked
477 in changes to the repository, merge those changes into the work file.
480 If you have made modifications to the work file, attempts to check in
481 your changes. To do this, Emacs first reads the log entry for the new
482 revision (@pxref{Log Buffer}). If some other user has checked in
483 changes to the repository since you last checked it out, the checkin
484 fails. In that case, type @kbd{C-x v v} again to merge those changes
485 into your own work file; this puts the work file into a ``conflicted''
486 state. Type @kbd{C-x v v} to clear the ``conflicted'' state; VC then
487 regards the file as up-to-date and modified, and you can try to check
490 To pick up any recent changes from the repository @emph{without}
491 trying to commit your own changes, type @kbd{C-x v m @key{RET}}.
495 These rules also apply when you use RCS in its ``non-locking'' mode,
496 except that changes are not automatically merged from the repository.
497 Nothing informs you if another user has checked in changes in the same
498 file since you began editing it; when you check in your revision, his
499 changes are removed (however, they remain in the repository and are
500 thus not irrevocably lost). Therefore, you must verify that the
501 current revision is unchanged before checking in your changes. In
502 addition, locking is possible with RCS even in this mode: @kbd{C-x v
503 v} with an unmodified file locks the file, just as it does with RCS in
504 its normal locking mode (@pxref{VC With A Locking VCS}).
506 @node VC With A Locking VCS
507 @subsubsection Basic Version Control with Locking
509 Under a locking-based version control system (such as SCCS, and RCS
510 in its default mode), @kbd{C-x v v} does the following:
514 If the file is not locked, lock it and make it writable, so that you
518 If the file is locked by you, and contains changes, check in the
519 changes. In order to do this, Emacs first reads the log entry for the
520 new revision. @xref{Log Buffer}.
523 If the file is locked by you, but you have not changed it since you
524 locked it, release the lock and makes the file read-only again.
527 If the file is locked by some other user, ask whether you want to
528 ``steal the lock'' from that user. If you say yes, the file becomes
529 locked by you, but a message is sent to the person who had formerly
530 locked the file, to inform him of what has happened.
533 These rules also apply when you use CVS in locking mode, except
534 that there is no such thing as stealing a lock.
536 @node Advanced C-x v v
537 @subsubsection Advanced Control in @kbd{C-x v v}
539 @cindex revision ID to check in/out
540 When you give a prefix argument to @code{vc-next-action} (@kbd{C-u
541 C-x v v}), it still performs the next logical version control
542 operation, but accepts additional arguments to specify precisely how
547 If the file is modified (or locked), you can specify the revision ID
548 to use for the new version that you check in. This is one way
549 to create a new branch (@pxref{Branches}).
552 If the file is not modified (and unlocked), you can specify the
553 revision to select; this lets you start working from an older
554 revision, or on another branch. If you do not enter any revision,
555 that takes you to the highest (``head'') revision on the current
556 branch; therefore @kbd{C-u C-x v v @key{RET}} is a convenient way to
557 get the latest version of a file from the repository.
560 @cindex specific version control system
561 Instead of the revision ID, you can also specify the name of a
562 version control system. This is useful when one file is being managed
563 with two version control systems at the same time
565 (@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs
569 (@pxref{Local Version Control}).
575 @subsubsection Features of the Log Entry Buffer
577 When you check in changes, Emacs pops up a buffer called
578 @samp{*VC-Log*} for you to enter a log entry.
580 After you have finished editing the log message, type @kbd{C-c C-c}
581 to exit the buffer and commit the change.
583 @findex log-edit-show-files
584 @findex log-edit-show-diff
585 In the @samp{*VC-Log*} buffer, typing @kbd{C-c C-f}
586 (@code{log-edit-show-files}) displays a list of files in the VC
587 fileset you are committing. If you called @kbd{C-x v v} directly from
588 a work file, the VC fileset consists of that single file, so this
589 command is not very useful. If you called @kbd{C-x v v} from a VC
590 directory buffer, the VC fileset may consist of multiple files
591 (@pxref{VC Directory Mode}).
593 @findex log-edit-insert-changelog
594 Type @kbd{C-c C-d} (@code{log-edit-show-diff}) to show a ``diff'' of
595 the changes you have made (i.e., the differences between the work file
596 and the repository revision from which you started editing the file).
597 The diff is displayed in a special buffer in another window.
598 @xref{Comparing Files}.
600 If you have written an entry in the @file{ChangeLog} (@pxref{Change
601 Log}), type @kbd{C-c C-a} (@code{log-edit-insert-changelog}) to pull
602 it into the @samp{*VC-Log*} buffer. If the topmost item in the
603 @file{ChangeLog} was made under your user name on the current date,
604 this command searches that item for entries that match the file(s) to
605 be committed; if found, these entries are inserted.
607 @xref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features},
610 @xref{Change Logs and VC},
612 for the opposite way of working---generating ChangeLog entries from
613 the revision control log.
615 To abort a check-in, just @strong{don't} type @kbd{C-c C-c} in that
616 buffer. You can switch buffers and do other editing. As long as you
617 don't try to check in another file, the entry you were editing remains
618 in the @samp{*VC-Log*} buffer, and you can go back to that buffer at
619 any time to complete the check-in.
621 If you change several source files for the same reason, it is often
622 convenient to specify the same log entry for many of the files. (This
623 is the normal way to do things on a changeset-oriented system, where
624 comments are attached to changesets rather than the history of
625 individual files.) The most convenient way to do this is to mark all
626 the files in VC Directory Mode and check in from there; the log buffer
627 will carry the fileset information with it and do a group commit when
628 you type @kbd{C-c C-c}.
630 You can also browse the history of previous log entries to duplicate
631 a checkin comment. This can be useful when you want several files to
632 have checkin comments that vary only slightly from each other. The
633 commands @kbd{M-n}, @kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this
634 work just like the minibuffer history commands (except that these
635 versions are used outside the minibuffer).
637 @vindex vc-log-mode-hook
638 Each time you check in a change, the log entry buffer is put into VC
639 Log Edit mode, which involves running two hooks: @code{text-mode-hook}
640 and @code{vc-log-mode-hook}. @xref{Hooks}.
643 @subsection Examining And Comparing Old Revisions
645 One of the convenient features of version control is the ability
646 to examine any revision of a file, or compare two revisions.
650 Prompt for a revision of the current file, and visit it in a buffer of
651 its own (@code{vc-revision-other-window}).
654 Compare the files in the current fileset with the working revision(s)
655 you started from (@code{vc-diff}). With a prefix argument, prompt for
656 two revisions of the current fileset and compare them. You can call
657 this command from a Dired buffer (@pxref{Dired}).
660 Compare the entire tree corresponding to the current fileset with the
661 tree you started from (@code{vc-root-diff}). With a prefix argument,
662 prompt for two revisions and compare their trees.
665 Display an annotated version of the file: for each line, show the
666 latest revision in which it was modified (@code{vc-annotate}).
669 @findex vc-revision-other-window
671 To examine an old revision, visit the work file and type @kbd{C-x v
672 ~ @var{revision} @key{RET}} (@code{vc-revision-other-window}). Here,
673 @var{revision} is either the desired revision ID (@pxref{VCS
674 Concepts}), or the name of a tag or branch
676 (@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}).
681 This command puts the text of the old revision in a file named
682 @file{@var{filename}.~@var{revision}~}, and visits it in its own
683 buffer in a separate window.
687 @kbd{C-x v =} (@code{vc-diff}) compares each file in the current VC
688 fileset (saving them if necessary) with the repository revision(s)
689 from which you started editing. Note that the latter may or may not
690 be the latest revision of the file(s). The diff is displayed in a
691 special buffer in another window. @xref{Comparing Files}.
695 To compare two arbitrary revisions of the current VC fileset, call
696 @code{vc-diff} with a prefix argument: @kbd{C-u C-x v =}. This
697 prompts for two revision IDs, using the minibuffer, and displays the
698 diff in a special buffer in another window. Instead of providing a
699 revision ID, you can give an empty input, which specifies the current
700 contents of the work file; or a tag or branch name
702 (@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}).
707 If your version control system is file-based (e.g. CVS) rather than
708 changeset-based (Subversion, GNU Arch, git, Mercurial), supplying a
709 revision ID for a multi-file fileset (as opposed to a symbolic tag
710 name) is unlikely to return diffs that are connected in any meaningful
713 The command @kbd{C-x v D} (@code{vc-root-diff}) is similar to
714 @kbd{C-x v =}, but it compares the entire tree associated with the
715 current VC fileset with the tree you started with. This means all the
716 files controlled by the current version control repository, even those
717 that are not part of the current VC fileset.
719 If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a buffer that
720 is neither visiting a version-controlled file nor a VC directory
721 buffer, these commands generate a diff of all registered files in the
722 current directory and its subdirectories.
724 @vindex vc-diff-switches
725 @vindex vc-rcs-diff-switches
726 @kbd{C-x v =} works by running a variant of the @code{diff} utility
727 designed to work with the version control system in use. The options
728 to pass to the @code{diff} command are taken from the first non-@code{nil}
729 value of @code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches},
730 and @code{diff-switches} (@pxref{Comparing Files}), in that order.
731 Since @code{nil} means to check the next variable in the sequence,
732 either of the first two may use the value @code{t} to mean no switches at all.
733 Most of the @samp{vc@dots{}diff-switches} variables default to
734 @code{nil}, but some default to @code{t}. These are for those version
735 control systems (e.g. SVN) whose @code{diff} implementations do not
736 accept common options (e.g. @samp{-c}) likely to be in
737 @code{diff-switches}.
739 The buffer produced by @kbd{C-x v =} supports the commands of
740 Compilation mode (@pxref{Compilation Mode}), such as @kbd{C-x `} and
741 @kbd{C-c C-c}, in both the ``old'' and ``new'' text, and they always
742 find the corresponding locations in the current work file. (Older
743 revisions are not, in general, present as files on your disk.)
747 For some back ends, you can display the file @dfn{annotated} with
748 per-line revision information, by typing @kbd{C-x v g}
749 (@code{vc-annotate}). This creates a new buffer (the ``annotate
750 buffer'') displaying the file's text, with each part colored to show
751 how old it is. Text colored red is new, blue means old, and
752 intermediate colors indicate intermediate ages. By default, the color
753 is scaled over the full range of ages, such that the oldest changes
754 are blue, and the newest changes are red.
756 When you give a prefix argument to this command, Emacs reads two
757 arguments using the minibuffer: the ID of which revision to display and
758 annotate (instead of the current file contents), and the time span in
759 days the color range should cover.
761 From the annotate buffer, these and other color scaling options are
762 available from the @samp{VC-Annotate} menu. In this buffer, you can
763 also use the following keys to browse the annotations of past revisions,
764 view diffs, or view log entries:
768 Annotate the previous revision, that is to say, the revision before
769 the one currently annotated. A numeric prefix argument is a repeat
770 count, so @kbd{C-u 10 p} would take you back 10 revisions.
773 Annotate the next revision---the one after the revision currently
774 annotated. A numeric prefix argument is a repeat count.
777 Annotate the revision indicated by the current line.
780 Annotate the revision before the one indicated by the current line.
781 This is useful to see the state the file was in before the change on
782 the current line was made.
785 Show in a buffer the file revision indicated by the current line.
788 Display the diff between the current line's revision and the previous
789 revision. This is useful to see what the current line's revision
790 actually changed in the file.
793 Display the diff between the current line's revision and the previous
794 revision for all files in the changeset (for VC systems that support
795 changesets). This is useful to see what the current line's revision
796 actually changed in the tree.
799 Show the log of the current line's revision. This is useful to see
800 the author's description of the changes in the revision on the current
804 Annotate the working revision--the one you are editing. If you used
805 @kbd{p} and @kbd{n} to browse to other revisions, use this key to
806 return to your working revision.
809 Toggle the annotation visibility. This is useful for looking just at
810 the file contents without distraction from the annotations.
813 @node Secondary VC Commands
814 @subsection The Secondary Commands of VC
816 This section explains the secondary commands of VC.
819 * Registering:: Putting a file under version control.
820 * VC Change Log:: Viewing the VC Change Log.
821 * VC Undo:: Canceling changes before or after check-in.
825 @subsubsection Registering a File for Version Control
829 You can put any file under version control by simply visiting it, and
830 then typing @w{@kbd{C-x v i}} (@code{vc-register}).
834 Register the visited file for version control.
837 To register the file, Emacs must choose which version control system
838 to use for it. If the file's directory already contains files
839 registered in a version control system, Emacs uses that system. If
840 there is more than one system in use for a directory, Emacs uses the
841 one that appears first in @code{vc-handled-backends}
843 (@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
846 (@pxref{Customizing VC}).
848 On the other hand, if there are no files already registered, Emacs uses
849 the first system from @code{vc-handled-backends} that could register
850 the file (for example, you cannot register a file under CVS if its
851 directory is not already part of a CVS tree); with the default value
852 of @code{vc-handled-backends}, this means that Emacs uses RCS in this
855 If locking is in use, @kbd{C-x v i} leaves the file unlocked and
856 read-only. Type @kbd{C-x v v} if you wish to start editing it. After
857 registering a file with CVS, you must subsequently commit the initial
858 revision by typing @kbd{C-x v v}. Until you do that, the revision ID
859 appears as @samp{@@@@} in the mode line.
861 @vindex vc-default-init-revision
862 @cindex initial revision ID to register
863 The default initial revision ID for a newly registered file
864 varies by what VCS you are using; normally it will be 1.1 on VCSes
865 that use dot-pair revision IDs and 1 on VCSes that use monotonic IDs.
866 You can specify a different default by setting the variable
867 @code{vc-default-init-revision}, or you can give @kbd{C-x v i} a
868 numeric argument; then it reads the initial revision ID for this
869 particular file using the minibuffer.
871 @vindex vc-initial-comment
872 If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an
873 initial comment to describe the purpose of this source file. Reading
874 the initial comment works like reading a log entry (@pxref{Log Buffer}).
877 @subsubsection VC Change Log
881 Display revision control state and change history
882 (@code{vc-print-log}).
885 Display the change history for the current repository
886 (@code{vc-print-root-log}).
891 The command @kbd{C-x v l} (@code{vc-print-log}) displays a buffer
892 named @samp{*vc-change-log*} in a new window. This buffer lists the
893 changes to the current file, including the associated log entries.
894 (These are the log entries associated with the version control system,
895 i.e. the ones you enter via the @samp{*VC-Log*} buffer. @xref{Log
896 Buffer}.) Point is centered at the revision of the file currently
897 being visited. With a prefix argument, the command prompts for the
898 revision to center on, and the maximum number of revisions to display.
899 You can call this command from a Dired buffer (@pxref{Dired}).
901 @findex vc-print-root-log
902 Type @kbd{C-x v L} (@code{vc-print-root-log}) to display a
903 @samp{*vc-change-log*} buffer showing the history of the
904 version-controlled directory tree as a whole. With a prefix argument,
905 the command prompts for the maximum number of revisions to display.
906 RCS, SCCS, and CVS do not support this feature.
908 In the @samp{*vc-change-log*} buffer, you can use the following keys
909 to move between the logs of revisions and of files, to view past
910 revisions, to modify change comments, to view annotations and to view
915 Move to the previous revision-item in the buffer. (Revision entries in the log
916 buffer are usually in reverse-chronological order, so the previous
917 revision-item usually corresponds to a newer revision.) A numeric
918 prefix argument is a repeat count.
921 Move to the next revision-item (which most often corresponds to the
922 previous revision of the file). A numeric prefix argument is a repeat
926 Move to the log of the previous file, when the logs of multiple files
927 are in the log buffer (@pxref{VC Directory Mode}). Otherwise, just
928 move to the beginning of the log. A numeric prefix argument is a
929 repeat count, so @kbd{C-u 10 P} would move backward 10 files.
932 Move to the log of the next file, when the logs of multiple files are
933 in the log buffer (@pxref{VC Directory Mode}). It also takes a
934 numeric prefix argument as a repeat count.
937 Annotate the revision indicated by the current line.
940 Modify the change comment displayed at point. Note that not all VC
941 systems support modifying change comments.
944 Visit the revision indicated at the current line, like typing @kbd{C-x
945 v ~} and specifying this revision's ID (@pxref{Old Revisions}).
948 Display the diff (@pxref{Comparing Files}) between the revision
949 indicated at the current line and the next earlier revision. This is
950 useful to see what actually changed in the file when the revision
951 indicated on the current line was committed.
954 Display the changeset diff (@pxref{Comparing Files}) between the
955 revision indicated at the current line and the next earlier revision.
956 This is useful to see all the changes to all files that the revision
957 indicated on the current line did when it was committed.
960 @vindex vc-log-show-limit
961 Because fetching many log entries can be slow, the
962 @samp{*vc-change-log*} buffer displays no more than 2000 revisions by
963 default. The variable @code{vc-log-show-limit} specifies this limit;
964 if you set the value to zero, that removes the limit. You can also
965 increase the number of revisions shown in an existing
966 @samp{*vc-change-log*} buffer by clicking on the @samp{Show 2X
967 entries} or @samp{Show unlimited entries} buttons at the end of the
968 buffer. However, RCS, SCCS, and CVS do not support this feature.
971 @subsubsection Undoing Version Control Actions
975 Revert the buffer and the file to the working revision from which you started
979 Remove the last-entered change from the master for the visited file.
980 This undoes your last check-in.
984 @findex vc-revert-buffer
985 If you want to discard your current set of changes and revert to the
986 working revision from which you started editing the file, use @kbd{C-x
987 v u} (@code{vc-revert-buffer}). If the version control system is
988 locking-based, this leaves the file unlocked, and you must lock it
989 again before making new changes. @kbd{C-x v u} requires confirmation,
990 unless it sees that you haven't made any changes with respect to the
991 master copy of the working revision.
993 @kbd{C-x v u} is also the command to unlock a file if you lock it and
994 then decide not to change it.
998 To cancel a change that you already checked in, use @kbd{C-x v c}
999 (@code{vc-rollback}). This command discards all record of the most
1000 recent checked-in revision, but only if your work file corresponds to
1001 that revision---you cannot use @kbd{C-x v c} to cancel a revision that
1002 is not the latest on its branch. Note that many version control
1003 systems do not support rollback at all; this command is something of a
1006 @node VC Directory Mode
1007 @subsection VC Directory Mode
1011 When you are working on a large program, it is often useful to find
1012 out which files have changed within an entire directory tree, or to
1013 view the status of all files under version control at once, and to
1014 perform version control operations on collections of files. You can
1015 use the command @kbd{C-x v d} (@code{vc-dir}) to make a directory
1016 listing that includes only files relevant for version control. This
1017 creates a @dfn{VC Directory buffer} and displays it in a separate
1022 @cindex CVS directory mode
1023 The VC Directory buffer works with all the version control systems
1024 that VC supports. For CVS, Emacs also offers a more powerful facility
1025 called PCL-CVS. @xref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The
1026 Emacs Front-End to CVS}.
1029 * Buffer: VC Directory Buffer. What the buffer looks like and means.
1030 * Commands: VC Directory Commands. Commands to use in a VC directory buffer.
1033 @node VC Directory Buffer
1034 @subsubsection The VC Directory Buffer
1036 The VC Directory buffer contains a list of version-controlled files
1037 in the current directory and its subdirectories. Files which are
1038 up-to-date (have no local differences from the repository copy) are
1039 usually hidden; if all files in a subdirectory are up-to-date, the
1040 subdirectory is hidden as well. There is an exception to this rule:
1041 if VC mode detects that a file has changed to an up-to-date state
1042 since you last looked at it, that file and its state are shown.
1044 If a directory uses more that one version control system, you can
1045 select which system to use for the @code{vc-dir} command by invoking
1046 @code{vc-dir} with a prefix argument: @kbd{C-u C-x v d}.
1048 The line for an individual file shows the version control state of
1049 the file. Under RCS and SCCS, the name of the user locking the file
1050 is shown; under CVS, an abbreviated version of the @samp{cvs status}
1051 output is used. Here is an example using CVS:
1057 needs-update file2.c
1063 In this example, @samp{file1.c} is modified with respect to the
1064 repository, and @samp{file2.c} is not. @samp{file3.c} is modified,
1065 but other changes have also been checked in to the repository---you
1066 need to merge them with the work file before you can check it in.
1068 @vindex vc-stay-local
1069 @vindex vc-cvs-stay-local
1070 In the above, if the repository were on a remote machine, VC only
1071 contacts it when the variable @code{vc-stay-local} (or
1072 @code{vc-cvs-stay-local}) is @code{nil}
1074 (@pxref{CVS Options,,,emacs-xtra, Specialized Emacs Features}).
1077 (@pxref{CVS Options}).
1079 This is because access to the repository may be slow, or you may be
1080 working offline and not have access to the repository at all. As a
1081 consequence, VC would not be able to tell you that @samp{file3.c} is
1082 in the ``merge'' state; you would learn that only when you try to
1083 check-in your modified copy of the file, or use a command such as
1086 In practice, this is not a problem because CVS handles this case
1087 consistently whenever it arises. In VC, you'll simply get prompted to
1088 merge the remote changes into your work file first. The benefits of
1089 less network communication usually outweigh the disadvantage of not
1090 seeing remote changes immediately.
1092 @vindex vc-directory-exclusion-list
1093 When a VC directory displays subdirectories it omits some that
1094 should never contain any files under version control. By default,
1095 this includes Version Control subdirectories such as @samp{RCS} and
1096 @samp{CVS}; you can customize this by setting the variable
1097 @code{vc-directory-exclusion-list}.
1099 @node VC Directory Commands
1100 @subsubsection VC Directory Commands
1102 VC Directory mode has a full set of navigation and marking commands
1103 for picking out filesets. Some of these are also available in a
1104 context menu invoked by the @kbd{mouse-2} button.
1106 Up- and down-arrow keys move in the buffer; @kbd{n} and @kbd{p} also
1107 move vertically as in other list-browsing modes. @key{SPC} and
1108 @key{TAB} behave like down-arrow, and @key{BackTab} behaves like
1111 Both @kbd{C-m} and @kbd{f} visit the file on the current
1112 line. @kbd{o} visits that file in another window. @kbd{q} dismisses
1113 the directory buffer.
1115 @kbd{x} hides up-to-date files.
1117 @kbd{m} marks the file or directory on the current line. If the
1118 region is active, @kbd{m} marks all the files in the region. There
1119 are some restrictions when marking: a file cannot be marked if any of
1120 its parent directories are marked, and a directory cannot be marked if
1121 any files in it or in its child directories are marked.
1123 @kbd{M} marks all the files with the same VC state as the current
1124 file if the cursor is on a file. If the cursor is on a directory, it
1125 marks all child files. With a prefix argument: marks all files and
1128 @kbd{u} unmarks the file or directory on the current line. If the
1129 region is active, it unmarks all the files in the region.
1131 @kbd{U} marks all the files with the same VC state as the current file
1132 if the cursor is on a file. If the cursor is on a directory, it
1133 unmarks all child files. With a prefix argument: unmarks all marked
1134 files and directories.
1136 It is possible to do search, search and replace, incremental search,
1137 and incremental regexp search on multiple files. These commands will
1138 work on all the marked files or the current file if nothing is marked.
1139 If a directory is marked, the files in that directory shown in the VC
1140 directory buffer will be used.
1142 @kbd{S} searches the marked files.
1144 @kbd{Q} does a query replace on the marked files.
1146 @kbd{M-s a C-s} does an incremental search on the marked files.
1148 @kbd{M-s a C-M-s} does an incremental search on the marked files.
1150 Commands are also accessible from the VC-dir menu. Note that some VC
1151 backends use the VC-dir menu to make available extra backend specific
1154 Normal VC commands with the @kbd{C-x v} prefix work in VC directory
1155 buffers. Some single-key shortcuts are available as well; @kbd{=},
1156 @kbd{+}, @kbd{l}, @kbd{i}, and @kbd{v} behave as through prefixed with
1159 The command @kbd{C-x v v} (@code{vc-next-action}) operates on all the
1160 marked files, so that you can check in several files at once.
1161 If the underlying VC supports atomic commits of multiple-file
1162 changesets, @kbd{C-x v v} with a selected set of modified but not
1163 committed files will commit all of them at once as a single changeset.
1165 When @kbd{C-x v v} (@code{vc-next-action}) operates on multiple
1166 files, all of those files must be either in the same state or in
1167 compatible states (added, modified and removed states are considered
1168 compatible). Otherwise it signals an error. This differs from the
1169 behavior of older versions of VC, which did not have fileset
1170 operations and simply did @code{vc-next-action} on each file
1173 If any files are in a state that calls for commit, @kbd{C-x v v} reads a
1174 single log entry and uses it for the changeset as a whole. If the
1175 underling VCS is file- rather than changeset-oriented, the log entry
1176 will be replicated into the history of each file.
1179 @subsection Multiple Branches of a File
1180 @cindex branch (version control)
1181 @cindex trunk (version control)
1183 One use of version control is to maintain multiple ``current''
1184 revisions of a file. For example, you might have different revisions of a
1185 program in which you are gradually adding various unfinished new
1186 features. Each such independent line of development is called a
1187 @dfn{branch}. VC allows you to create branches, switch between
1188 different branches, and merge changes from one branch to another.
1189 Please note, however, that branches are not supported for SCCS.
1191 A file's main line of development is usually called the @dfn{trunk}.
1192 You can create multiple branches from the trunk. How the difference
1193 between trunk and branch is made visible is dependent on whether the
1194 VCS uses dot-pair or monotonic version IDs.
1196 In VCSes with dot-pair revision IDs, the revisions on the trunk are
1197 normally IDed 1.1, 1.2, 1.3, etc. At any such revision, you can
1198 start an independent branch. A branch starting at revision 1.2 would
1199 have revision ID 1.2.1.1, and consecutive revisions on this branch
1200 would have IDs 1.2.1.2, 1.2.1.3, 1.2.1.4, and so on. If there is
1201 a second branch also starting at revision 1.2, it would consist of
1202 revisions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc.
1204 In VCSes with monotonic revision IDs, trunk revisions are IDed as
1205 1, 2, 3, etc. A branch from (say) revision 2 might start with 2.1 and
1206 continue through 2.2, 2.3, etc. But naming conventions for branches
1207 and subbranches vary widely on these systems, and some (like
1208 Mercurial) never depart from the monotonic integer sequence at all.
1209 Consult the documentation of the VCS you are using.
1211 @cindex head revision
1212 If you omit the final component of a dot-pair revision ID, that is called a
1213 @dfn{branch ID}. It refers to the highest existing revision on that
1214 branch---the @dfn{head revision} of that branch. The branches in the
1215 dot-pair example above have branch IDs 1.2.1 and 1.2.2.
1218 * Switching Branches:: How to get to another existing branch.
1219 * Creating Branches:: How to start a new branch.
1220 * Merging:: Transferring changes between branches.
1221 * Multi-User Branching:: Multiple users working at multiple branches
1225 @node Switching Branches
1226 @subsubsection Switching between Branches
1228 To switch between branches, type @kbd{C-u C-x v v} and specify the
1229 revision ID you want to select. On a locking-based system, this
1230 version is then visited @emph{unlocked} (write-protected), so you can
1231 examine it before locking it. Switching branches in this way is allowed
1232 only when the file is not locked.
1234 On a VCS with dot-pair IDs, you can omit the minor part, thus giving
1235 only the branch ID; this takes you to the head version on the
1236 chosen branch. If you only type @key{RET}, Emacs goes to the highest
1237 version on the trunk.
1239 After you have switched to any branch (including the main branch), you
1240 stay on it for subsequent VC commands, until you explicitly select some
1243 @node Creating Branches
1244 @subsubsection Creating New Branches
1246 To create a new branch from a head revision (one that is the latest in
1247 the branch that contains it), first select that revision if necessary,
1248 lock it with @kbd{C-x v v}, and make whatever changes you want. Then,
1249 when you check in the changes, use @kbd{C-u C-x v v}. This lets you
1250 specify the revision ID for the new revision. You should specify a
1251 suitable branch ID for a branch starting at the current revision.
1252 For example, if the current revision is 2.5, the branch ID should be
1253 2.5.1, 2.5.2, and so on, depending on the number of existing branches at
1256 To create a new branch at an older revision (one that is no longer the
1257 head of a branch), first select that revision (@pxref{Switching
1258 Branches}). Your procedure will then differ depending on whether you
1259 are using a locking or merging-based VCS.
1261 On a locking VCS, you will need to lock the old revision branch with
1262 @kbd{C-x v v}. You'll be asked to confirm, when you lock the old
1263 revision, that you really mean to create a new branch---if you say no,
1264 you'll be offered a chance to lock the latest revision instead. On
1265 a merging-based VCS you will skip this step.
1267 Then make your changes and type @kbd{C-x v v} again to check in a new
1268 revision. This automatically creates a new branch starting from the
1269 selected revision. You need not specially request a new branch, because
1270 that's the only way to add a new revision at a point that is not the head
1273 After the branch is created, you ``stay'' on it. That means that
1274 subsequent check-ins create new revisions on that branch. To leave the
1275 branch, you must explicitly select a different revision with @kbd{C-u C-x
1276 v v}. To transfer changes from one branch to another, use the merge
1277 command, described in the next section.
1280 @subsubsection Merging Branches
1282 @cindex merging changes
1283 When you have finished the changes on a certain branch, you will
1284 often want to incorporate them into the file's main line of development
1285 (the trunk). This is not a trivial operation, because development might
1286 also have proceeded on the trunk, so that you must @dfn{merge} the
1287 changes into a file that has already been changed otherwise. VC allows
1288 you to do this (and other things) with the @code{vc-merge} command.
1291 @item C-x v m (vc-merge)
1292 Merge changes into the work file.
1297 @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it
1298 into the current version of the work file. It firsts asks you in the
1299 minibuffer where the changes should come from. If you just type
1300 @key{RET}, Emacs merges any changes that were made on the same branch
1301 since you checked the file out (we call this @dfn{merging the news}).
1302 This is the common way to pick up recent changes from the repository,
1303 regardless of whether you have already changed the file yourself.
1305 You can also enter a branch ID or a pair of revision IDs in
1306 the minibuffer. Then @kbd{C-x v m} finds the changes from that
1307 branch, or the differences between the two revisions you specified, and
1308 merges them into the current revision of the current file.
1310 As an example, suppose that you have finished a certain feature on
1311 branch 1.3.1. In the meantime, development on the trunk has proceeded
1312 to revision 1.5. To merge the changes from the branch to the trunk,
1313 first go to the head revision of the trunk, by typing @kbd{C-u C-x v v
1314 @key{RET}}. Revision 1.5 is now current. If locking is used for the file,
1315 type @kbd{C-x v v} to lock revision 1.5 so that you can change it. Next,
1316 type @kbd{C-x v m 1.3.1 @key{RET}}. This takes the entire set of changes on
1317 branch 1.3.1 (relative to revision 1.3, where the branch started, up to
1318 the last revision on the branch) and merges it into the current revision
1319 of the work file. You can now check in the changed file, thus creating
1320 revision 1.6 containing the changes from the branch.
1322 It is possible to do further editing after merging the branch, before
1323 the next check-in. But it is usually wiser to check in the merged
1324 revision, then lock it and make the further changes. This will keep
1325 a better record of the history of changes.
1328 @cindex resolving conflicts
1329 When you merge changes into a file that has itself been modified, the
1330 changes might overlap. We call this situation a @dfn{conflict}, and
1331 reconciling the conflicting changes is called @dfn{resolving a
1334 Whenever conflicts occur during merging, VC detects them, tells you
1335 about them in the echo area, and asks whether you want help in merging.
1336 If you say yes, it starts an Ediff session (@pxref{Top,
1337 Ediff, Ediff, ediff, The Ediff Manual}).
1339 If you say no, the conflicting changes are both inserted into the
1340 file, surrounded by @dfn{conflict markers}. The example below shows how
1341 a conflict region looks; the file is called @samp{name} and the current
1342 master file revision with user B's changes in it is 1.11.
1344 @c @w here is so CVS won't think this is a conflict.
1348 @var{User A's version}
1350 @var{User B's version}
1355 @cindex vc-resolve-conflicts
1356 Then you can resolve the conflicts by editing the file manually. Or
1357 you can type @code{M-x vc-resolve-conflicts} after visiting the file.
1358 This starts an Ediff session, as described above. Don't forget to
1359 check in the merged version afterwards.
1361 @node Multi-User Branching
1362 @subsubsection Multi-User Branching
1364 It is often useful for multiple developers to work simultaneously on
1365 different branches of a file. CVS and later systems allow this by
1366 default; for RCS, it is possible if you create multiple source
1367 directories. Each source directory should have a link named
1368 @file{RCS} which points to a common directory of RCS master files.
1369 Then each source directory can have its own choice of selected
1370 revisions, but all share the same common RCS records.
1372 This technique works reliably and automatically, provided that the
1373 source files contain RCS version headers
1375 (@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}).
1378 (@pxref{Version Headers}).
1380 The headers enable Emacs to be sure, at all times, which revision
1381 ID is present in the work file.
1383 If the files do not have version headers, you must instead tell Emacs
1384 explicitly in each session which branch you are working on. To do this,
1385 first find the file, then type @kbd{C-u C-x v v} and specify the correct
1386 branch ID. This ensures that Emacs knows which branch it is using
1387 during this particular editing session.
1390 @include vc1-xtra.texi
1394 @section Change Logs
1397 A change log file contains a chronological record of when and why you
1398 have changed a program, consisting of a sequence of entries describing
1399 individual changes. Normally it is kept in a file called
1400 @file{ChangeLog} in the same directory as the file you are editing, or
1401 one of its parent directories. A single @file{ChangeLog} file can
1402 record changes for all the files in its directory and all its
1406 * Change Log Commands:: Commands for editing change log files.
1407 * Format of ChangeLog:: What the change log file looks like.
1410 @node Change Log Commands
1411 @subsection Change Log Commands
1414 @findex add-change-log-entry-other-window
1415 The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
1416 file for the file you are editing
1417 (@code{add-change-log-entry-other-window}). If that file is actually
1418 a backup file, it makes an entry appropriate for the file's
1419 parent---that is useful for making log entries for functions that
1420 have been deleted in the current version.
1422 @kbd{C-x 4 a} visits the change log file and creates a new entry
1423 unless the most recent entry is for today's date and your name. It
1424 also creates a new item for the current file. For many languages, it
1425 can even guess the name of the function or other object that was
1428 @vindex add-log-keep-changes-together
1429 When the variable @code{add-log-keep-changes-together} is
1430 non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file
1431 rather than starting a new item.
1433 @vindex add-log-always-start-new-record
1434 If @code{add-log-always-start-new-record} is non-@code{nil},
1435 @kbd{C-x 4 a} always makes a new entry, even if the last entry
1436 was made by you and on the same date.
1438 @vindex change-log-version-info-enabled
1439 @vindex change-log-version-number-regexp-list
1440 @cindex file version in change log entries
1441 If the value of the variable @code{change-log-version-info-enabled}
1442 is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the
1443 change log entry. It finds the version number by searching the first
1444 ten percent of the file, using regular expressions from the variable
1445 @code{change-log-version-number-regexp-list}.
1447 @cindex Change Log mode
1448 @findex change-log-mode
1449 The change log file is visited in Change Log mode. In this major
1450 mode, each bunch of grouped items counts as one paragraph, and each
1451 entry is considered a page. This facilitates editing the entries.
1452 @kbd{C-j} and auto-fill indent each new line like the previous line;
1453 this is convenient for entering the contents of an entry.
1455 You can use the @code{next-error} command (by default bound to
1456 @kbd{C-x `}) to move between entries in the Change Log, when Change
1457 Log mode is on. You will jump to the actual site in the file that was
1458 changed, not just to the next Change Log entry. You can also use
1459 @code{previous-error} to move back in the same list.
1461 @findex change-log-merge
1462 You can use the command @kbd{M-x change-log-merge} to merge other
1463 log files into a buffer in Change Log Mode, preserving the date
1464 ordering of entries.
1466 Version control systems are another way to keep track of changes in
1467 your program and keep a change log. In the VC log buffer, typing
1468 @kbd{C-c C-a} (@code{log-edit-insert-changelog}) inserts the relevant
1469 Change Log entry, if one exists (@pxref{Log Buffer}). You can also
1470 insert a VC log entry into a Change Log buffer by typing @kbd{C-x v a}
1471 (@code{vc-update-change-log}) in the Change Log buffer
1473 (@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
1476 (@pxref{Change Logs and VC}).
1479 @node Format of ChangeLog
1480 @subsection Format of ChangeLog
1482 A change log entry starts with a header line that contains the current
1483 date, your name, and your email address (taken from the variable
1484 @code{add-log-mailing-address}). Aside from these header lines, every
1485 line in the change log starts with a space or a tab. The bulk of the
1486 entry consists of @dfn{items}, each of which starts with a line starting
1487 with whitespace and a star. Here are two entries, both dated in May
1488 1993, with two items and one item respectively.
1494 1993-05-25 Richard Stallman <rms@@gnu.org>
1496 * man.el: Rename symbols `man-*' to `Man-*'.
1497 (manual-entry): Make prompt string clearer.
1499 * simple.el (blink-matching-paren-distance):
1500 Change default to 12,000.
1502 1993-05-24 Richard Stallman <rms@@gnu.org>
1504 * vc.el (minor-mode-map-alist): Don't use it if it's void.
1505 (vc-cancel-version): Doc fix.
1508 One entry can describe several changes; each change should have its
1509 own item, or its own line in an item. Normally there should be a
1510 blank line between items. When items are related (parts of the same
1511 change, in different places), group them by leaving no blank line
1514 You should put a copyright notice and permission notice at the
1515 end of the change log file. Here is an example:
1518 Copyright 1997, 1998 Free Software Foundation, Inc.
1519 Copying and distribution of this file, with or without modification, are
1520 permitted provided the copyright notice and this notice are preserved.
1524 Of course, you should substitute the proper years and copyright holder.
1527 @section Tags Tables
1528 @cindex tags and tag tables
1530 A @dfn{tag} is a reference to a subunit in a program or in a
1531 document. In program source code, tags reference syntactic elements
1532 of the program: functions, subroutines, data types, macros, etc. In a
1533 document, tags reference chapters, sections, appendices, etc. Each
1534 tag specifies the name of the file where the corresponding subunit is
1535 defined, and the position of the subunit's definition in that file.
1537 A @dfn{tags table} records the tags extracted by scanning the source
1538 code of a certain program or a certain document. Tags extracted from
1539 generated files reference the original files, rather than the
1540 generated files that were scanned during tag extraction. Examples of
1541 generated files include C files generated from Cweb source files, from
1542 a Yacc parser, or from Lex scanner definitions; @file{.i} preprocessed
1543 C files; and Fortran files produced by preprocessing @file{.fpp}
1546 To produce a tags table, you use the @samp{etags} command,
1547 submitting it a document or the source code of a program.
1548 @samp{etags} writes the tags to a @dfn{tags table file}, or @dfn{tags
1549 file} in short. The conventional name for a tags file is @file{TAGS}.
1551 Emacs uses the information recorded in tags tables in commands that
1552 search or replace through multiple source files: these commands use
1553 the names of the source files recorded in the tags table to know which
1554 files to search. Other commands, such as @kbd{M-.}, which finds the
1555 definition of a function, use the recorded information about the
1556 function names and positions to find the source file and the position
1557 within that file where the function is defined.
1559 @cindex C++ class browser, tags
1561 @cindex class browser, C++
1563 See also the Ebrowse facility, which is tailored for C++.
1564 @xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}.
1567 * Tag Syntax:: Tag syntax for various types of code and text files.
1568 * Create Tags Table:: Creating a tags table with @code{etags}.
1569 * Etags Regexps:: Create arbitrary tags using regular expressions.
1570 * Select Tags Table:: How to visit a tags table.
1571 * Find Tag:: Commands to find the definition of a specific tag.
1572 * Tags Search:: Using a tags table for searching and replacing.
1573 * List Tags:: Listing and finding tags defined in a file.
1577 @subsection Source File Tag Syntax
1579 Here is how tag syntax is defined for the most popular languages:
1583 In C code, any C function or typedef is a tag, and so are definitions of
1584 @code{struct}, @code{union} and @code{enum}.
1585 @code{#define} macro definitions, @code{#undef} and @code{enum}
1587 tags, unless you specify @samp{--no-defines} when making the tags table.
1588 Similarly, global variables are tags, unless you specify
1589 @samp{--no-globals}, and so are struct members, unless you specify
1590 @samp{--no-members}. Use of @samp{--no-globals}, @samp{--no-defines}
1591 and @samp{--no-members} can make the tags table file much smaller.
1593 You can tag function declarations and external variables in addition
1594 to function definitions by giving the @samp{--declarations} option to
1598 In C++ code, in addition to all the tag constructs of C code, member
1599 functions are also recognized; member variables are also recognized,
1600 unless you use the @samp{--no-members} option. Tags for variables and
1601 functions in classes are named @samp{@var{class}::@var{variable}} and
1602 @samp{@var{class}::@var{function}}. @code{operator} definitions have
1603 tag names like @samp{operator+}.
1606 In Java code, tags include all the constructs recognized in C++, plus
1607 the @code{interface}, @code{extends} and @code{implements} constructs.
1608 Tags for variables and functions in classes are named
1609 @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
1612 In La@TeX{} text, the argument of any of the commands @code{\chapter},
1613 @code{\section}, @code{\subsection}, @code{\subsubsection},
1614 @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite},
1615 @code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry},
1616 @code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand},
1617 @code{\newenvironment} or @code{\renewenvironment} is a tag.@refill
1619 Other commands can make tags as well, if you specify them in the
1620 environment variable @env{TEXTAGS} before invoking @code{etags}. The
1621 value of this environment variable should be a colon-separated list of
1622 command names. For example,
1625 TEXTAGS="mycommand:myothercommand"
1630 specifies (using Bourne shell syntax) that the commands
1631 @samp{\mycommand} and @samp{\myothercommand} also define tags.
1634 In Lisp code, any function defined with @code{defun}, any variable
1635 defined with @code{defvar} or @code{defconst}, and in general the first
1636 argument of any expression that starts with @samp{(def} in column zero is
1640 In Scheme code, tags include anything defined with @code{def} or with a
1641 construct whose name starts with @samp{def}. They also include variables
1642 set with @code{set!} at top level in the file.
1645 Several other languages are also supported:
1650 In Ada code, functions, procedures, packages, tasks and types are
1651 tags. Use the @samp{--packages-only} option to create tags for
1654 In Ada, the same name can be used for different kinds of entity
1655 (e.g.@:, for a procedure and for a function). Also, for things like
1656 packages, procedures and functions, there is the spec (i.e.@: the
1657 interface) and the body (i.e.@: the implementation). To make it
1658 easier to pick the definition you want, Ada tag name have suffixes
1659 indicating the type of entity:
1676 Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
1677 directly to the body of the package @code{bidule}, while @kbd{M-x
1678 find-tag @key{RET} bidule @key{RET}} will just search for any tag
1682 In assembler code, labels appearing at the beginning of a line,
1683 followed by a colon, are tags.
1686 In Bison or Yacc input files, each rule defines as a tag the nonterminal
1687 it constructs. The portions of the file that contain C code are parsed
1691 In Cobol code, tags are paragraph names; that is, any word starting in
1692 column 8 and followed by a period.
1695 In Erlang code, the tags are the functions, records and macros defined
1699 In Fortran code, functions, subroutines and block data are tags.
1702 In HTML input files, the tags are the @code{title} and the @code{h1},
1703 @code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchors
1704 and all occurrences of @code{id=}.
1707 In Lua input files, all functions are tags.
1710 In makefiles, targets are tags; additionally, variables are tags
1711 unless you specify @samp{--no-globals}.
1714 In Objective C code, tags include Objective C definitions for classes,
1715 class categories, methods and protocols. Tags for variables and
1716 functions in classes are named @samp{@var{class}::@var{variable}} and
1717 @samp{@var{class}::@var{function}}.
1720 In Pascal code, the tags are the functions and procedures defined in
1724 In Perl code, the tags are the packages, subroutines and variables
1725 defined by the @code{package}, @code{sub}, @code{my} and @code{local}
1726 keywords. Use @samp{--globals} if you want to tag global variables.
1727 Tags for subroutines are named @samp{@var{package}::@var{sub}}. The
1728 name for subroutines defined in the default package is
1729 @samp{main::@var{sub}}.
1732 In PHP code, tags are functions, classes and defines. Vars are tags
1733 too, unless you use the @samp{--no-members} option.
1736 In PostScript code, the tags are the functions.
1739 In Prolog code, tags are predicates and rules at the beginning of
1743 In Python code, @code{def} or @code{class} at the beginning of a line
1747 You can also generate tags based on regexp matching (@pxref{Etags
1748 Regexps}) to handle other formats and languages.
1750 @node Create Tags Table
1751 @subsection Creating Tags Tables
1752 @cindex @code{etags} program
1754 The @code{etags} program is used to create a tags table file. It knows
1755 the syntax of several languages, as described in
1757 the previous section.
1762 Here is how to run @code{etags}:
1765 etags @var{inputfiles}@dots{}
1769 The @code{etags} program reads the specified files, and writes a tags
1770 table named @file{TAGS} in the current working directory. You can
1771 optionally specify a different file name for the tags table by using the
1772 @samp{--output=@var{file}} option; specifying @file{-} as a file name
1773 prints the tags table to standard output.
1775 If the specified files don't exist, @code{etags} looks for
1776 compressed versions of them and uncompresses them to read them. Under
1777 MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz}
1778 if it is given @samp{mycode.c} on the command line and @file{mycode.c}
1781 @code{etags} recognizes the language used in an input file based on
1782 its file name and contents. You can specify the language with the
1783 @samp{--language=@var{name}} option, described below.
1785 If the tags table data become outdated due to changes in the files
1786 described in the table, the way to update the tags table is the same
1787 way it was made in the first place. If the tags table fails to record
1788 a tag, or records it for the wrong file, then Emacs cannot possibly
1789 find its definition until you update the tags table. However, if the
1790 position recorded in the tags table becomes a little bit wrong (due to
1791 other editing), the worst consequence is a slight delay in finding the
1792 tag. Even if the stored position is very far wrong, Emacs will still
1793 find the tag, after searching most of the file for it. That delay is
1794 hardly noticeable with today's computers.
1796 Thus, there is no need to update the tags table after each edit.
1797 You should update a tags table when you define new tags that you want
1798 to have listed, or when you move tag definitions from one file to
1799 another, or when changes become substantial.
1801 One tags table can virtually include another. Specify the included
1802 tags file name with the @samp{--include=@var{file}} option when
1803 creating the file that is to include it. The latter file then acts as
1804 if it covered all the source files specified in the included file, as
1805 well as the files it directly contains.
1807 If you specify the source files with relative file names when you run
1808 @code{etags}, the tags file will contain file names relative to the
1809 directory where the tags file was initially written. This way, you can
1810 move an entire directory tree containing both the tags file and the
1811 source files, and the tags file will still refer correctly to the source
1812 files. If the tags file is @file{-} or is in the @file{/dev} directory,
1813 however, the file names are
1814 made relative to the current working directory. This is useful, for
1815 example, when writing the tags to @file{/dev/stdout}.
1817 When using a relative file name, it should not be a symbolic link
1818 pointing to a tags file in a different directory, because this would
1819 generally render the file names invalid.
1821 If you specify absolute file names as arguments to @code{etags}, then
1822 the tags file will contain absolute file names. This way, the tags file
1823 will still refer to the same files even if you move it, as long as the
1824 source files remain in the same place. Absolute file names start with
1825 @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
1827 When you want to make a tags table from a great number of files, you
1828 may have problems listing them on the command line, because some systems
1829 have a limit on its length. The simplest way to circumvent this limit
1830 is to tell @code{etags} to read the file names from its standard input,
1831 by typing a dash in place of the file names, like this:
1834 find . -name "*.[chCH]" -print | etags -
1837 Use the option @samp{--language=@var{name}} to specify the language
1838 explicitly. You can intermix these options with file names; each one
1839 applies to the file names that follow it. Specify
1840 @samp{--language=auto} to tell @code{etags} to resume guessing the
1841 language from the file names and file contents. Specify
1842 @samp{--language=none} to turn off language-specific processing
1843 entirely; then @code{etags} recognizes tags by regexp matching alone
1844 (@pxref{Etags Regexps}).
1846 The option @samp{--parse-stdin=@var{file}} is mostly useful when
1847 calling @code{etags} from programs. It can be used (only once) in
1848 place of a file name on the command line. @code{Etags} will read from
1849 standard input and mark the produced tags as belonging to the file
1852 @samp{etags --help} outputs the list of the languages @code{etags}
1853 knows, and the file name rules for guessing the language. It also prints
1854 a list of all the available @code{etags} options, together with a short
1855 explanation. If followed by one or more @samp{--language=@var{lang}}
1856 options, it outputs detailed information about how tags are generated for
1860 @subsection Etags Regexps
1862 The @samp{--regex} option provides a general way of recognizing tags
1863 based on regexp matching. You can freely intermix this option with
1864 file names, and each one applies to the source files that follow it.
1865 If you specify multiple @samp{--regex} options, all of them are used
1866 in parallel. The syntax is:
1869 --regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers}
1872 The essential part of the option value is @var{tagregexp}, the
1873 regexp for matching tags. It is always used anchored, that is, it
1874 only matches at the beginning of a line. If you want to allow
1875 indented tags, use a regexp that matches initial whitespace; start it
1878 In these regular expressions, @samp{\} quotes the next character, and
1879 all the GCC character escape sequences are supported (@samp{\a} for
1880 bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for
1881 escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for
1882 carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab).
1884 Ideally, @var{tagregexp} should not match more characters than are
1885 needed to recognize what you want to tag. If the syntax requires you
1886 to write @var{tagregexp} so it matches more characters beyond the tag
1887 itself, you should add a @var{nameregexp}, to pick out just the tag.
1888 This will enable Emacs to find tags more accurately and to do
1889 completion on tag names more reliably. You can find some examples
1892 The @var{modifiers} are a sequence of zero or more characters that
1893 modify the way @code{etags} does the matching. A regexp with no
1894 modifiers is applied sequentially to each line of the input file, in a
1895 case-sensitive way. The modifiers and their meanings are:
1899 Ignore case when matching this regexp.
1901 Match this regular expression against the whole file, so that
1902 multi-line matches are possible.
1904 Match this regular expression against the whole file, and allow
1905 @samp{.} in @var{tagregexp} to match newlines.
1908 The @samp{-R} option cancels all the regexps defined by preceding
1909 @samp{--regex} options. It too applies to the file names following
1910 it. Here's an example:
1913 etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
1914 bar.ber -R --lang=lisp los.er
1918 Here @code{etags} chooses the parsing language for @file{voo.doo} and
1919 @file{bar.ber} according to their contents. @code{etags} also uses
1920 @var{reg1} to recognize additional tags in @file{voo.doo}, and both
1921 @var{reg1} and @var{reg2} to recognize additional tags in
1922 @file{bar.ber}. @var{reg1} is checked against each line of
1923 @file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while
1924 @var{reg2} is checked against the whole @file{bar.ber} file,
1925 permitting multi-line matches, in a case-sensitive way. @code{etags}
1926 uses only the Lisp tags rules, with no user-specified regexp matching,
1927 to recognize tags in @file{los.er}.
1929 You can restrict a @samp{--regex} option to match only files of a
1930 given language by using the optional prefix @var{@{language@}}.
1931 (@samp{etags --help} prints the list of languages recognized by
1932 @code{etags}.) This is particularly useful when storing many
1933 predefined regular expressions for @code{etags} in a file. The
1934 following example tags the @code{DEFVAR} macros in the Emacs source
1935 files, for the C language only:
1938 --regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
1942 When you have complex regular expressions, you can store the list of
1943 them in a file. The following option syntax instructs @code{etags} to
1944 read two files of regular expressions. The regular expressions
1945 contained in the second file are matched without regard to case.
1948 --regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file}
1952 A regex file for @code{etags} contains one regular expression per
1953 line. Empty lines, and lines beginning with space or tab are ignored.
1954 When the first character in a line is @samp{@@}, @code{etags} assumes
1955 that the rest of the line is the name of another file of regular
1956 expressions; thus, one such file can include another file. All the
1957 other lines are taken to be regular expressions. If the first
1958 non-whitespace text on the line is @samp{--}, that line is a comment.
1960 For example, we can create a file called @samp{emacs.tags} with the
1964 -- This is for GNU Emacs C source files
1965 @{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
1969 and then use it like this:
1972 etags --regex=@@emacs.tags *.[ch] */*.[ch]
1975 Here are some more examples. The regexps are quoted to protect them
1976 from shell interpretation.
1984 etags --language=none \
1985 --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
1986 --regex='/###key \(.*\)/\1/' \
1987 --regex='/[ \t]*global[ \t].*/' \
1992 Note that tags are not generated for scripts, so that you have to add
1993 a line by yourself of the form @samp{###key @var{scriptname}} if you
2000 etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
2007 etags --language=none \
2008 --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
2009 --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
2010 \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
2014 @node Select Tags Table
2015 @subsection Selecting a Tags Table
2017 @vindex tags-file-name
2018 @findex visit-tags-table
2019 Emacs has at any time one @dfn{selected} tags table, and all the
2020 commands for working with tags tables use the selected one. To select
2021 a tags table, type @kbd{M-x visit-tags-table}, which reads the tags
2022 table file name as an argument, with @file{TAGS} in the default
2023 directory as the default.
2025 Emacs does not actually read in the tags table contents until you
2026 try to use them; all @code{visit-tags-table} does is store the file
2027 name in the variable @code{tags-file-name}, and setting the variable
2028 yourself is just as good. The variable's initial value is @code{nil};
2029 that value tells all the commands for working with tags tables that
2030 they must ask for a tags table file name to use.
2032 Using @code{visit-tags-table} when a tags table is already loaded
2033 gives you a choice: you can add the new tags table to the current list
2034 of tags tables, or start a new list. The tags commands use all the tags
2035 tables in the current list. If you start a new list, the new tags table
2036 is used @emph{instead} of others. If you add the new table to the
2037 current list, it is used @emph{as well as} the others.
2039 @vindex tags-table-list
2040 You can specify a precise list of tags tables by setting the variable
2041 @code{tags-table-list} to a list of strings, like this:
2043 @c keep this on two lines for formatting in smallbook
2046 (setq tags-table-list
2047 '("~/emacs" "/usr/local/lib/emacs/src"))
2052 This tells the tags commands to look at the @file{TAGS} files in your
2053 @file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
2054 directory. The order depends on which file you are in and which tags
2055 table mentions that file, as explained above.
2057 Do not set both @code{tags-file-name} and @code{tags-table-list}.
2060 @subsection Finding a Tag
2062 The most important thing that a tags table enables you to do is to find
2063 the definition of a specific tag.
2066 @item M-.@: @var{tag} @key{RET}
2067 Find first definition of @var{tag} (@code{find-tag}).
2069 Find next alternate definition of last tag specified.
2071 Go back to previous tag found.
2072 @item C-M-. @var{pattern} @key{RET}
2073 Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
2075 Find the next tag whose name matches the last pattern used.
2076 @item C-x 4 .@: @var{tag} @key{RET}
2077 Find first definition of @var{tag}, but display it in another window
2078 (@code{find-tag-other-window}).
2079 @item C-x 5 .@: @var{tag} @key{RET}
2080 Find first definition of @var{tag}, and create a new frame to select the
2081 buffer (@code{find-tag-other-frame}).
2083 Pop back to where you previously invoked @kbd{M-.} and friends.
2088 @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
2089 a specified tag. It searches through the tags table for that tag, as a
2090 string, and then uses the tags table info to determine the file that the
2091 definition is in and the approximate character position in the file of
2092 the definition. Then @code{find-tag} visits that file, moves point to
2093 the approximate character position, and searches ever-increasing
2094 distances away to find the tag definition.
2096 If an empty argument is given (just type @key{RET}), the balanced
2097 expression in the buffer before or around point is used as the
2098 @var{tag} argument. @xref{Expressions}.
2100 You don't need to give @kbd{M-.} the full name of the tag; a part
2101 will do. This is because @kbd{M-.} finds tags in the table which
2102 contain @var{tag} as a substring. However, it prefers an exact match
2103 to a substring match. To find other tags that match the same
2104 substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
2105 M-.}; this does not read a tag name, but continues searching the tags
2106 table's text for another tag containing the same substring last used.
2107 If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier
2108 alternative to @kbd{C-u M-.}.
2111 @findex find-tag-other-window
2113 @findex find-tag-other-frame
2114 Like most commands that can switch buffers, @code{find-tag} has a
2115 variant that displays the new buffer in another window, and one that
2116 makes a new frame for it. The former is @w{@kbd{C-x 4 .}}, which invokes
2117 the command @code{find-tag-other-window}. The latter is @w{@kbd{C-x 5 .}},
2118 which invokes @code{find-tag-other-frame}.
2120 To move back to places you've found tags recently, use @kbd{C-u -
2121 M-.}; more generally, @kbd{M-.} with a negative numeric argument. This
2122 command can take you to another buffer. @w{@kbd{C-x 4 .}} with a negative
2123 argument finds the previous tag location in another window.
2126 @findex pop-tag-mark
2127 @vindex find-tag-marker-ring-length
2128 As well as going back to places you've found tags recently, you can go
2129 back to places @emph{from where} you found them. Use @kbd{M-*}, which
2130 invokes the command @code{pop-tag-mark}, for this. Typically you would
2131 find and study the definition of something with @kbd{M-.} and then
2132 return to where you were with @kbd{M-*}.
2134 Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
2135 a depth determined by the variable @code{find-tag-marker-ring-length}.
2137 @findex find-tag-regexp
2139 The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
2140 match a specified regular expression. It is just like @kbd{M-.} except
2141 that it does regexp matching instead of substring matching.
2144 @subsection Searching and Replacing with Tags Tables
2145 @cindex search and replace in multiple files
2146 @cindex multiple-file search and replace
2148 The commands in this section visit and search all the files listed
2149 in the selected tags table, one by one. For these commands, the tags
2150 table serves only to specify a sequence of files to search. These
2151 commands scan the list of tags tables starting with the first tags
2152 table (if any) that describes the current file, proceed from there to
2153 the end of the list, and then scan from the beginning of the list
2154 until they have covered all the tables in the list.
2157 @item M-x tags-search @key{RET} @var{regexp} @key{RET}
2158 Search for @var{regexp} through the files in the selected tags
2160 @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
2161 Perform a @code{query-replace-regexp} on each file in the selected tags table.
2163 Restart one of the commands above, from the current location of point
2164 (@code{tags-loop-continue}).
2168 @kbd{M-x tags-search} reads a regexp using the minibuffer, then
2169 searches for matches in all the files in the selected tags table, one
2170 file at a time. It displays the name of the file being searched so you
2171 can follow its progress. As soon as it finds an occurrence,
2172 @code{tags-search} returns.
2175 @findex tags-loop-continue
2176 Having found one match, you probably want to find all the rest. To find
2177 one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
2178 @code{tags-search}. This searches the rest of the current buffer, followed
2179 by the remaining files of the tags table.@refill
2181 @findex tags-query-replace
2182 @kbd{M-x tags-query-replace} performs a single
2183 @code{query-replace-regexp} through all the files in the tags table. It
2184 reads a regexp to search for and a string to replace with, just like
2185 ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
2186 tags-search}, but repeatedly, processing matches according to your
2187 input. @xref{Replace}, for more information on query replace.
2189 @vindex tags-case-fold-search
2190 @cindex case-sensitivity and tags search
2191 You can control the case-sensitivity of tags search commands by
2192 customizing the value of the variable @code{tags-case-fold-search}. The
2193 default is to use the same setting as the value of
2194 @code{case-fold-search} (@pxref{Search Case}).
2196 It is possible to get through all the files in the tags table with a
2197 single invocation of @kbd{M-x tags-query-replace}. But often it is
2198 useful to exit temporarily, which you can do with any input event that
2199 has no special query replace meaning. You can resume the query
2200 replace subsequently by typing @kbd{M-,}; this command resumes the
2201 last tags search or replace command that you did. For instance, to
2202 skip the rest of the current file, you can type @kbd{M-> M-,}.
2204 The commands in this section carry out much broader searches than the
2205 @code{find-tag} family. The @code{find-tag} commands search only for
2206 definitions of tags that match your substring or regexp. The commands
2207 @code{tags-search} and @code{tags-query-replace} find every occurrence
2208 of the regexp, as ordinary search commands and replace commands do in
2211 These commands create buffers only temporarily for the files that they
2212 have to search (those which are not already visited in Emacs buffers).
2213 Buffers in which no match is found are quickly killed; the others
2216 It may have struck you that @code{tags-search} is a lot like
2217 @code{grep}. You can also run @code{grep} itself as an inferior of
2218 Emacs and have Emacs show you the matching lines one by one.
2219 @xref{Grep Searching}.
2222 @subsection Tags Table Inquiries
2225 @item M-x list-tags @key{RET} @var{file} @key{RET}
2226 Display a list of the tags defined in the program file @var{file}.
2227 @item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
2228 Display a list of all tags matching @var{regexp}.
2232 @kbd{M-x list-tags} reads the name of one of the files described by
2233 the selected tags table, and displays a list of all the tags defined in
2234 that file. The ``file name'' argument is really just a string to
2235 compare against the file names recorded in the tags table; it is read as
2236 a string rather than as a file name. Therefore, completion and
2237 defaulting are not available, and you must enter the file name the same
2238 way it appears in the tags table. Do not include a directory as part of
2239 the file name unless the file name recorded in the tags table includes a
2242 @findex tags-apropos
2243 @vindex tags-apropos-verbose
2244 @kbd{M-x tags-apropos} is like @code{apropos} for tags
2245 (@pxref{Apropos}). It finds all the tags in the selected tags table
2246 whose entries match @var{regexp}, and displays them. If the variable
2247 @code{tags-apropos-verbose} is non-@code{nil}, it displays the names
2248 of the tags files together with the tag names.
2250 @vindex tags-tag-face
2251 @vindex tags-apropos-additional-actions
2252 You can customize the appearance of the output by setting the
2253 variable @code{tags-tag-face} to a face. You can display additional
2254 output with @kbd{M-x tags-apropos} by customizing the variable
2255 @code{tags-apropos-additional-actions}---see its documentation for
2258 You can also use the collection of tag names to complete a symbol
2259 name in the buffer. @xref{Symbol Completion}.
2262 @include emerge-xtra.texi
2266 arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb