1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2012
3 @c Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Maintaining, Abbrevs, Building, Top
6 @chapter Maintaining Large Programs
8 This chapter describes Emacs features for maintaining large
9 programs. In addition to the features described here, you may find
10 the @file{ERT} (``Emacs Lisp Regression Testing'') library useful in
11 this context (@pxref{Top,,ERT,ert, Emacs Lisp Regression Testing}).
14 * Version Control:: Using version control systems.
15 * Change Log:: Maintaining a change history for your program.
16 * Tags:: Go directly to any function in your program in one
17 command. Tags remembers which file it is in.
18 * EDE:: An integrated development environment for Emacs.
20 * Emerge:: A convenient way of merging two versions of a program.
25 @section Version Control
26 @cindex version control
28 A @dfn{version control system} is a program that can record multiple
29 versions of a source file, storing information such as the creation
30 time of each version, who made it, and a description of what was
33 The Emacs version control interface is called @dfn{VC}. VC commands
34 work with several different version control systems; currently, it
35 supports GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS,
36 SCCS/CSSC, and Subversion. Of these, the GNU project distributes CVS,
37 Arch, RCS, and Bazaar.
39 VC is enabled automatically whenever you visit a file governed by a
40 version control system. To disable VC entirely, set the customizable
41 variable @code{vc-handled-backends} to @code{nil}
43 (@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
46 (@pxref{Customizing VC}).
50 * Introduction to VC:: How version control works in general.
51 * VC Mode Line:: How the mode line shows version control status.
52 * Basic VC Editing:: How to edit a file under version control.
53 * Log Buffer:: Features available in log entry buffers.
54 * Registering:: Putting a file under version control.
55 * Old Revisions:: Examining and comparing old versions.
56 * VC Change Log:: Viewing the VC Change Log.
57 * VC Undo:: Canceling changes before or after committing.
58 * VC Directory Mode:: Listing files managed by version control.
59 * Branches:: Multiple lines of development.
61 * Miscellaneous VC:: Various other commands and features of VC.
62 * Customizing VC:: Variables that change VC's behavior.
66 @node Introduction to VC
67 @subsection Introduction to Version Control
69 VC allows you to use a version control system from within Emacs,
70 integrating the version control operations smoothly with editing. It
71 provides a uniform interface for common operations in many version
74 Some uncommon or intricate version control operations, such as
75 altering repository settings, are not supported in VC. You should
76 perform such tasks outside Emacs, e.g.@: via the command line.
78 This section provides a general overview of version control, and
79 describes the version control systems that VC supports. You can skip
80 this section if you are already familiar with the version control system
84 * Why Version Control?:: Understanding the problems it addresses.
85 * Version Control Systems:: Supported version control back-end systems.
86 * VCS Concepts:: Words and concepts related to version control.
87 * VCS Merging:: How file conflicts are handled.
88 * VCS Changesets:: How changes are grouped.
89 * VCS Repositories:: Where version control repositories are stored.
90 * Types of Log File:: The VCS log in contrast to the ChangeLog.
93 @node Why Version Control?
94 @subsubsection Understanding the problems it addresses
96 Version control systems provide you with three important
101 @dfn{Reversibility}: the ability to back up to a previous state if you
102 discover that some modification you did was a mistake or a bad idea.
105 @dfn{Concurrency}: the ability to have many people modifying the same
106 collection of files knowing that conflicting modifications can be
107 detected and resolved.
110 @dfn{History}: the ability to attach historical data to your data,
111 such as explanatory comments about the intention behind each change to
112 it. Even for a programmer working solo, change histories are an
113 important aid to memory; for a multi-person project, they are a
114 vitally important form of communication among developers.
117 @node Version Control Systems
118 @subsubsection Supported Version Control Systems
120 @cindex back end (version control)
121 VC currently works with many different version control systems,
122 which it refers to as @dfn{back ends}:
128 SCCS was the first version control system ever built, and was long ago
129 superseded by more advanced ones. VC compensates for certain features
130 missing in SCCS (e.g.@: tag names for releases) by implementing them
131 itself. Other VC features, such as multiple branches, are simply
132 unavailable. Since SCCS is non-free, we recommend avoiding it.
136 CSSC is a free replacement for SCCS. You should use CSSC only if, for
137 some reason, you cannot use a more recent and better-designed version
142 RCS is the free version control system around which VC was initially
143 built. It is relatively primitive: it cannot be used over the
144 network, and works at the level of individual files. Almost
145 everything you can do with RCS can be done through VC.
149 CVS is the free version control system that was, until recently (circa
150 2008), used by the majority of free software projects. Nowadays, it
151 is slowly being superseded by newer systems. CVS allows concurrent
152 multi-user development either locally or over the network. Unlike
153 newer systems, it lacks support for atomic commits and file
154 moving/renaming. VC supports all basic editing operations under CVS.
159 Subversion (svn) is a free version control system designed to be
160 similar to CVS but without its problems (e.g., it supports atomic
161 commits of filesets, and versioning of directories, symbolic links,
162 meta-data, renames, copies, and deletes).
167 GNU Arch is one of the earliest @dfn{decentralized} version control
168 systems (the other being Monotone). @xref{VCS Concepts}, for a
169 description of decentralized version control systems. It is no longer
170 under active development, and has been deprecated in favor of Bazaar.
174 Git is a decentralized version control system originally invented by
175 Linus Torvalds to support development of Linux (his kernel). VC
176 supports many common Git operations, but others, such as repository
177 syncing, must be done from the command line.
182 Mercurial (hg) is a decentralized version control system broadly
183 resembling Git. VC supports most Mercurial commands, with the
184 exception of repository sync operations.
189 Bazaar (bzr) is a decentralized version control system that supports
190 both repository-based and decentralized versioning. VC supports most
191 basic editing operations under Bazaar.
195 @subsubsection Concepts of Version Control
198 @cindex registered file
199 When a file is under version control, we say that it is
200 @dfn{registered} in the version control system. The system has a
201 @dfn{repository} which stores both the file's present state and its
202 change history---enough to reconstruct the current version or any
203 earlier version. The repository also contains other information, such
204 as @dfn{log entries} that describe the changes made to each file.
207 @cindex checking out files
208 The copy of a version-controlled file that you actually edit is
209 called the @dfn{work file}. You can change each work file as you
210 would an ordinary file. After you are done with a set of changes, you
211 may @dfn{commit} (or @dfn{check in}) the changes; this records the
212 changes in the repository, along with a descriptive log entry.
215 A directory tree of work files is called a @dfn{working tree}.
219 Each commit creates a new @dfn{revision} in the repository. The
220 version control system keeps track of all past revisions and the
221 changes that were made in each revision. Each revision is named by a
222 @dfn{revision ID}, whose format depends on the version control system;
223 in the simplest case, it is just an integer.
225 To go beyond these basic concepts, you will need to understand three
226 aspects in which version control systems differ. As explained in the
227 next three sections, they can be lock-based or merge-based; file-based
228 or changeset-based; and centralized or decentralized. VC handles all
229 these modes of operation, but it cannot hide the differences.
232 @subsubsection Merge-based vs lock-based Version Control
234 A version control system typically has some mechanism to coordinate
235 between users who want to change the same file. There are two ways to
236 do this: merging and locking.
238 @cindex merging-based version
239 In a version control system that uses merging, each user may modify
240 a work file at any time. The system lets you @dfn{merge} your work
241 file, which may contain changes that have not been committed, with the
242 latest changes that others have committed.
244 @cindex locking-based version
245 Older version control systems use a @dfn{locking} scheme instead.
246 Here, work files are normally read-only. To edit a file, you ask the
247 version control system to make it writable for you by @dfn{locking}
248 it; only one user can lock a given file at any given time. This
249 procedure is analogous to, but different from, the locking that Emacs
250 uses to detect simultaneous editing of ordinary files
251 (@pxref{Interlocking}). When you commit your changes, that unlocks
252 the file, and the work file becomes read-only again. Other users may
253 then lock the file to make their own changes.
255 Both locking and merging systems can have problems when multiple
256 users try to modify the same file at the same time. Locking systems
257 have @dfn{lock conflicts}; a user may try to check a file out and be
258 unable to because it is locked. In merging systems, @dfn{merge
259 conflicts} happen when you commit a change to a file that conflicts
260 with a change committed by someone else after your checkout. Both
261 kinds of conflict have to be resolved by human judgment and
262 communication. Experience has shown that merging is superior to
263 locking, both in convenience to developers and in minimizing the
264 number and severity of conflicts that actually occur.
266 SCCS always uses locking. RCS is lock-based by default but can be
267 told to operate in a merging style. CVS and Subversion are
268 merge-based by default but can be told to operate in a locking mode.
269 Decentralized version control systems, such as GNU Arch, Git, and
270 Mercurial, are exclusively merging-based.
272 VC mode supports both locking and merging version control. The
273 terms ``commit'' and ``update'' are used in newer version control
274 systems; older lock-based systems use the terms ``check in'' and
275 ``check out''. VC hides the differences between them as much as
279 @subsubsection Changeset-based vs File-based Version Control
281 @cindex file-based version control
282 On SCCS, RCS, CVS, and other early version control systems, version
283 control operations are @dfn{file-based}: each file has its own comment
284 and revision history separate from that of all other files. Newer
285 systems, beginning with Subversion, are @dfn{changeset-based}: a
286 commit may include changes to several files, and the entire set of
287 changes is handled as a unit. Any comment associated with the change
288 does not belong to a single file, but to the changeset itself.
290 @cindex changeset-based version control
291 Changeset-based version control is more flexible and powerful than
292 file-based version control; usually, when a change to multiple files
293 has to be reversed, it's good to be able to easily identify and remove
296 @node VCS Repositories
297 @subsubsection Decentralized vs Centralized Repositories
299 @cindex centralized version control
300 @cindex decentralized version control
301 @cindex distributed version control
302 Early version control systems were designed around a
303 @dfn{centralized} model in which each project has only one repository
304 used by all developers. SCCS, RCS, CVS, and Subversion share this
305 kind of model. One of its drawbacks is that the repository is a choke
306 point for reliability and efficiency.
308 GNU Arch pioneered the concept of @dfn{distributed} or
309 @dfn{decentralized} version control, later implemented in Git,
310 Mercurial, and Bazaar. A project may have several different
311 repositories, and these systems support a sort of super-merge between
312 repositories that tries to reconcile their change histories. In
313 effect, there is one repository for each developer, and repository
314 merges take the place of commit operations.
316 VC helps you manage the traffic between your personal workfiles and
317 a repository. Whether the repository is a single master, or one of a
318 network of peer repositories, is not something VC has to care about.
320 @node Types of Log File
321 @subsubsection Types of Log File
322 @cindex types of log file
323 @cindex log File, types of
324 @cindex version control log
326 Projects that use a version control system can have two types of log
327 for changes. One is the log maintained by the version control system:
328 each time you commit a change, you fill out a @dfn{log entry} for the
329 change (@pxref{Log Buffer}). This is called the @dfn{version control
332 The other kind of log is the file @file{ChangeLog} (@pxref{Change
333 Log}). It provides a chronological record of all changes to a large
334 portion of a program---typically one directory and its subdirectories.
335 A small program would use one @file{ChangeLog} file; a large program
336 may have a @file{ChangeLog} file in each major directory.
337 @xref{Change Log}. Programmers have used change logs since long
338 before version control systems.
340 Changeset-based version systems typically maintain a changeset-based
341 modification log for the entire system, which makes change log files
342 somewhat redundant. One advantage that they retain is that it is
343 sometimes useful to be able to view the transaction history of a
344 single directory separately from those of other directories.
346 A project maintained with version control can use just the version
347 control log, or it can use both kinds of logs. It can handle some
348 files one way and some files the other way. Each project has its
349 policy, which you should follow.
351 When the policy is to use both, you typically want to write an entry
352 for each change just once, then put it into both logs. You can write
353 the entry in @file{ChangeLog}, then copy it to the log buffer with
354 @kbd{C-c C-a} when committing the change (@pxref{Log Buffer}). Or you
355 can write the entry in the log buffer while committing the change, and
356 later use the @kbd{C-x v a} command to copy it to @file{ChangeLog}
358 (@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
361 (@pxref{Change Logs and VC}).
365 @subsection Version Control and the Mode Line
366 @cindex VC mode line indicator
368 When you visit a file that is under version control, Emacs indicates
369 this on the mode line. For example, @samp{Bzr-1223} says that Bazaar
370 is used for that file, and the current revision ID is 1223.
372 @cindex version control status
373 The character between the back-end name and the revision ID
374 indicates the @dfn{version control status} of the work file. In a
375 merge-based version control system, a @samp{-} character indicates
376 that the work file is unmodified, and @samp{:} indicates that it has
377 been modified. @samp{!} indicates that the file contains conflicts as
378 result of a recent merge operation (@pxref{Merging}), or that the file
379 was removed from the version control. Finally, @samp{?} means that
380 the file is under version control, but is missing from the working
383 In a lock-based system, @samp{-} indicates an unlocked file, and
384 @samp{:} a locked file; if the file is locked by another user (for
385 instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
386 @samp{@@} means that the file was locally added, but not yet committed
387 to the master repository.
389 On a graphical display, you can move the mouse over this mode line
390 indicator to pop up a ``tool-tip'', which displays a more verbose
391 description of the version control status. Pressing @kbd{Mouse-1}
392 over the indicator pops up a menu of VC commands, identical to
393 @samp{Tools / Version Control} on the menu bar.
395 @vindex auto-revert-check-vc-info
396 When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is
397 under version control, it updates the version control information in
398 the mode line. However, Auto Revert mode may not properly update this
399 information if the version control status changes without changes to
400 the work file, from outside the current Emacs session. If you set
401 @code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates
402 the version control status information every
403 @code{auto-revert-interval} seconds, even if the work file itself is
404 unchanged. The resulting CPU usage depends on the version control
405 system, but is usually not excessive.
407 @node Basic VC Editing
408 @subsection Basic Editing under Version Control
412 Most VC commands operate on @dfn{VC filesets}. A VC fileset is a
413 collection of one or more files that a VC operation acts on. When you
414 type VC commands in a buffer visiting a version-controlled file, the
415 VC fileset is simply that one file. When you type them in a VC
416 Directory buffer, and some files in it are marked, the VC fileset
417 consists of the marked files (@pxref{VC Directory Mode}).
419 On modern changeset-based version control systems (@pxref{VCS
420 Changesets}), VC commands handle multi-file VC filesets as a group.
421 For example, committing a multi-file VC fileset generates a single
422 revision, containing the changes to all those files. On older
423 file-based version control systems like CVS, each file in a multi-file
424 VC fileset is handled individually; for example, a commit generates
425 one revision for each changed file.
429 Perform the next appropriate version control operation on the current
433 @findex vc-next-action
435 The principal VC command is a multi-purpose command, @kbd{C-x v v}
436 (@code{vc-next-action}), which performs the ``most appropriate''
437 action on the current VC fileset: either registering it with a version
438 control system, or committing it, or unlocking it, or merging changes
439 into it. The precise actions are described in detail in the following
440 subsections. You can use @kbd{C-x v v} either in a file-visiting
441 buffer or in a VC Directory buffer.
443 Note that VC filesets are distinct from the ``named filesets'' used
444 for viewing and visiting files in functional groups
445 (@pxref{Filesets}). Unlike named filesets, VC filesets are not named
446 and don't persist across sessions.
449 * VC With A Merging VCS:: Without locking: default mode for CVS.
450 * VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS.
451 * Advanced C-x v v:: Advanced features available with a prefix argument.
454 @node VC With A Merging VCS
455 @subsubsection Basic Version Control with Merging
457 On a merging-based version control system (i.e.@: most modern ones;
458 @pxref{VCS Merging}), @kbd{C-x v v} does the following:
462 If there is more than one file in the VC fileset and the files have
463 inconsistent version control statuses, signal an error. (Note,
464 however, that a fileset is allowed to include both ``newly-added''
465 files and ``modified'' files; @pxref{Registering}.)
468 If none of the files in the VC fileset are registered with a version
469 control system, register the VC fileset, i.e.@: place it under version
470 control. @xref{Registering}. If Emacs cannot find a system to
471 register under, it prompts for a repository type, creates a new
472 repository, and registers the VC fileset with it.
475 If every work file in the VC fileset is unchanged, do nothing.
478 If every work file in the VC fileset has been modified, commit the
479 changes. To do this, Emacs pops up a @samp{*vc-log*} buffer; type the
480 desired log entry for the new revision, followed by @kbd{C-c C-c} to
481 commit. @xref{Log Buffer}.
483 If committing to a shared repository, the commit may fail if the
484 repository that has been changed since your last update. In that
485 case, you must perform an update before trying again. On a
486 decentralized version control system, use @kbd{C-x v +} (@pxref{VC
487 Pull}) or @kbd{C-x v m} (@pxref{Merging}). On a centralized version
488 control system, type @kbd{C-x v v} again to merge in the repository
492 Finally, if you are using a centralized version control system, check
493 if each work file in the VC fileset is up-to-date. If any file has
494 been changed in the repository, offer to update it.
497 These rules also apply when you use RCS in its ``non-locking'' mode,
498 except that changes are not automatically merged from the repository.
499 Nothing informs you if another user has committed changes in the same
500 file since you began editing it; when you commit your revision, his
501 changes are removed (however, they remain in the repository and are
502 thus not irrevocably lost). Therefore, you must verify that the
503 current revision is unchanged before committing your changes. In
504 addition, locking is possible with RCS even in this mode: @kbd{C-x v
505 v} with an unmodified file locks the file, just as it does with RCS in
506 its normal locking mode (@pxref{VC With A Locking VCS}).
508 @node VC With A Locking VCS
509 @subsubsection Basic Version Control with Locking
511 On a locking-based version control system (such as SCCS, and RCS in
512 its default mode), @kbd{C-x v v} does the following:
516 If there is more than one file in the VC fileset and the files have
517 inconsistent version control statuses, signal an error.
520 If each file in the VC fileset is not registered with a version
521 control system, register the VC fileset. @xref{Registering}. If
522 Emacs cannot find a system to register under, it prompts for a
523 repository type, creates a new repository, and registers the VC
527 If each file is registered and unlocked, lock it and make it writable,
528 so that you can begin to edit it.
531 If each file is locked by you and contains changes, commit the
532 changes. To do this, Emacs pops up a @samp{*vc-log*} buffer; type the
533 desired log entry for the new revision, followed by @kbd{C-c C-c} to
534 commit (@pxref{Log Buffer}).
537 If each file is locked by you, but you have not changed it, release
538 the lock and make the file read-only again.
541 If each file is locked by another user, ask whether you want to
542 ``steal the lock''. If you say yes, the file becomes locked by you,
543 and a warning message is sent to the user who had formerly locked the
547 These rules also apply when you use CVS in locking mode, except
548 that CVS does not support stealing locks.
550 @node Advanced C-x v v
551 @subsubsection Advanced Control in @kbd{C-x v v}
553 @cindex revision ID in version control
554 When you give a prefix argument to @code{vc-next-action} (@kbd{C-u
555 C-x v v}), it still performs the next logical version control
556 operation, but accepts additional arguments to specify precisely how
561 @cindex specific version control system
562 You can specify the name of a version control system. This is useful
563 if the fileset can be managed by more than one version control system,
564 and Emacs fails to detect the correct one.
567 Otherwise, if using CVS or RCS, you can specify a revision ID.
569 If the fileset is modified (or locked), this makes Emacs commit with
570 that revision ID. You can create a new branch by supplying an
571 appropriate revision ID (@pxref{Branches}).
573 If the fileset is unmodified (and unlocked), this checks the specified
574 revision into the working tree. You can also specify a revision on
575 another branch by giving its revision or branch ID (@pxref{Switching
576 Branches}). An empty argument (i.e.@: @kbd{C-u C-x v v @key{RET}})
577 checks out the latest (``head'') revision on the current branch.
579 This signals an error on a decentralized version control system.
580 Those systems do not let you specify your own revision IDs, nor do
581 they use the concept of ``checking out'' individual files.
585 @subsection Features of the Log Entry Buffer
587 @cindex C-c C-c @r{(Log Edit mode)}
588 @findex log-edit-done
589 When you tell VC to commit a change, it pops up a buffer named
590 @samp{*vc-log*}. In this buffer, you should write a @dfn{log entry}
591 describing the changes you have made (@pxref{Why Version Control?}).
592 After you are done, type @kbd{C-c C-c} (@code{log-edit-done}) to exit
593 the buffer and commit the change, together with your log entry.
595 @cindex Log Edit mode
596 @cindex mode, Log Edit
597 @vindex vc-log-mode-hook
598 The major mode for the @samp{*vc-log*} buffer is Log Edit mode, a
599 variant of Text mode (@pxref{Text Mode}). On entering Log Edit mode,
600 Emacs runs the hooks @code{text-mode-hook} and @code{vc-log-mode-hook}
603 In the @samp{*vc-log*} buffer, you can write one or more @dfn{header
604 lines}, specifying additional information to be supplied to the
605 version control system. Each header line must occupy a single line at
606 the top of the buffer; the first line that is not a header line is
607 treated as the start of the log entry. For example, the following
608 header line states that the present change was not written by you, but
609 by another developer:
612 Author: J. R. Hacker <jrh@@example.com>
616 Apart from the @samp{Author} header, Emacs recognizes the headers
617 @samp{Date} (a manually-specified commit time) and @samp{Fixes} (a
618 reference to a bug fixed by the change). Not all version control
619 systems recognize all headers: Bazaar recognizes all three headers,
620 while Git, Mercurial, and Monotone recognize only @samp{Author} and
621 @samp{Date}. If you specify a header for a system that does not
622 support it, the header is treated as part of the log entry.
624 @kindex C-c C-f @r{(Log Edit mode)}
625 @findex log-edit-show-files
626 @kindex C-c C-d @r{(Log Edit mode)}
627 @findex log-edit-show-diff
628 While in the @samp{*vc-log*} buffer, the ``current VC fileset'' is
629 considered to be the fileset that will be committed if you type
630 @w{@kbd{C-c C-c}}. To view a list of the files in the VC fileset,
631 type @w{@kbd{C-c C-f}} (@code{log-edit-show-files}). To view a diff
632 of changes between the VC fileset and the version from which you
633 started editing (@pxref{Old Revisions}), type @kbd{C-c C-d}
634 (@code{log-edit-show-diff}).
636 @kindex C-c C-a @r{(Log Edit mode)}
637 @findex log-edit-insert-changelog
638 If the VC fileset includes one or more @file{ChangeLog} files
639 (@pxref{Change Log}), type @kbd{C-c C-a}
640 (@code{log-edit-insert-changelog}) to pull the relevant entries into
641 the @samp{*vc-log*} buffer. If the topmost item in each
642 @file{ChangeLog} was made under your user name on the current date,
643 this command searches that item for entries matching the file(s) to be
644 committed, and inserts them.
646 If you are using CVS or RCS, see @ref{Change Logs and VC}, for the
647 opposite way of working---generating ChangeLog entries from the Log
651 To abort a commit, just @strong{don't} type @kbd{C-c C-c} in that
652 buffer. You can switch buffers and do other editing. As long as you
653 don't try to make another commit, the entry you were editing remains
654 in the @samp{*vc-log*} buffer, and you can go back to that buffer at
655 any time to complete the commit.
657 @kindex M-n @r{(Log Edit mode)}
658 @kindex M-p @r{(Log Edit mode)}
659 @kindex M-s @r{(Log Edit mode)}
660 @kindex M-r @r{(Log Edit mode)}
661 You can also browse the history of previous log entries to duplicate
662 a commit comment. This can be useful when you want to make several
663 commits with similar comments. The commands @kbd{M-n}, @kbd{M-p},
664 @kbd{M-s} and @kbd{M-r} for doing this work just like the minibuffer
665 history commands (@pxref{Minibuffer History}), except that they are
666 used outside the minibuffer.
669 @subsection Registering a File for Version Control
673 Register the visited file for version control.
678 The command @kbd{C-x v i} (@code{vc-register}) @dfn{registers} each
679 file in the current VC fileset, placing it under version control.
680 This is essentially equivalent to the action of @kbd{C-x v v} on an
681 unregistered VC fileset (@pxref{Basic VC Editing}), except that if the
682 VC fileset is already registered, @kbd{C-x v i} signals an error
683 whereas @kbd{C-x v v} performs some other action.
685 To register a file, Emacs must choose a version control system. For
686 a multi-file VC fileset, the VC Directory buffer specifies the system
687 to use (@pxref{VC Directory Mode}). For a single-file VC fileset, if
688 the file's directory already contains files registered in a version
689 control system, or if the directory is part of a directory tree
690 controlled by a version control system, Emacs chooses that system. In
691 the event that more than one version control system is applicable,
692 Emacs uses the one that appears first in the variable
694 @code{vc-handled-backends}.
697 @code{vc-handled-backends} (@pxref{Customizing VC}).
699 If Emacs cannot find a version control system to register the file
700 under, it prompts for a repository type, creates a new repository, and
701 registers the file into that repository.
703 On most version control systems, registering a file with @kbd{C-x v
704 i} or @kbd{C-x v v} adds it to the ``working tree'' but not to the
705 repository. Such files are labeled as @samp{added} in the VC
706 Directory buffer, and show a revision ID of @samp{@@@@} in the mode
707 line. To make the registration take effect in the repository, you
708 must perform a commit (@pxref{Basic VC Editing}). Note that a single
709 commit can include both file additions and edits to existing files.
711 On a locking-based version control system (@pxref{VCS Merging}),
712 registering a file leaves it unlocked and read-only. Type @kbd{C-x v
713 v} if you wish to start editing it.
716 @subsection Examining And Comparing Old Revisions
720 Compare the work files in the current VC fileset with the versions you
721 started from (@code{vc-diff}). With a prefix argument, prompt for two
722 revisions of the current VC fileset and compare them. You can also
723 call this command from a Dired buffer (@pxref{Dired}).
727 Like @kbd{C-x v =}, but using Ediff. @xref{Top, Ediff, ediff, The
732 Compare the entire working tree to the revision you started from
733 (@code{vc-root-diff}). With a prefix argument, prompt for two
734 revisions and compare their trees.
737 Prompt for a revision of the current file, and visit it in a separate
738 buffer (@code{vc-revision-other-window}).
741 Display an annotated version of the current file: for each line, show
742 the latest revision in which it was modified (@code{vc-annotate}).
747 @kbd{C-x v =} (@code{vc-diff}) displays a @dfn{diff} which compares
748 each work file in the current VC fileset to the version(s) from which
749 you started editing. The diff is displayed in another window, in a
750 Diff mode buffer (@pxref{Diff Mode}) named @file{*vc-diff*}. The
751 usual Diff mode commands are available in this buffer. In particular,
752 the @kbd{g} (@code{revert-buffer}) command performs the file
753 comparison again, generating a new diff.
756 To compare two arbitrary revisions of the current VC fileset, call
757 @code{vc-diff} with a prefix argument: @kbd{C-u C-x v =}. This
758 prompts for two revision IDs (@pxref{VCS Concepts}), and displays a
759 diff between those versions of the fileset. This will not work
760 reliably for multi-file VC filesets, if the version control system is
761 file-based rather than changeset-based (e.g.@: CVS), since then
762 revision IDs for different files would not be related in any
765 Instead of the revision ID, some version control systems let you
766 specify revisions in other formats. For instance, under Bazaar you
767 can enter @samp{date:yesterday} for the argument to @kbd{C-u C-x v =}
768 (and related commands) to specify the first revision committed after
769 yesterday. See the documentation of the version control system for
772 If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a Dired buffer
773 (@pxref{Dired}), the file listed on the current line is treated as the
778 @kbd{M-x vc-ediff} works like @kbd{C-x v =}, except that it uses an
779 Ediff session. @xref{Top, Ediff, ediff, The Ediff Manual}.
784 @kbd{C-x v D} (@code{vc-root-diff}) is similar to @kbd{C-x v =}, but
785 it displays the changes in the entire current working tree (i.e.@: the
786 working tree containing the current VC fileset). If you invoke this
787 command from a Dired buffer, it applies to the working tree containing
790 @vindex vc-diff-switches
791 You can customize the @command{diff} options that @kbd{C-x v =} and
792 @kbd{C-x v D} use for generating diffs. The options used are taken
793 from the first non-@code{nil} value amongst the variables
794 @code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches}, and
795 @code{diff-switches} (@pxref{Comparing Files}), in that order. Here,
796 @var{backend} stands for the relevant version control system,
797 e.g.@: @code{bzr} for Bazaar. Since @code{nil} means to check the
798 next variable in the sequence, either of the first two may use the
799 value @code{t} to mean no switches at all. Most of the
800 @code{vc-@var{backend}-diff-switches} variables default to @code{nil},
801 but some default to @code{t}; these are for version control systems
802 whose @code{diff} implementations do not accept common diff options,
805 @findex vc-revision-other-window
807 To directly examine an older version of a file, visit the work file
808 and type @kbd{C-x v ~ @var{revision} @key{RET}}
809 (@code{vc-revision-other-window}). This retrieves the file version
810 corresponding to @var{revision}, saves it to
811 @file{@var{filename}.~@var{revision}~}, and visits it in a separate
816 Many version control systems allow you to view files @dfn{annotated}
817 with per-line revision information, by typing @kbd{C-x v g}
818 (@code{vc-annotate}). This creates a new buffer (the ``annotate
819 buffer'') displaying the file's text, with each line colored to show
820 how old it is. Red text is new, blue is old, and intermediate colors
821 indicate intermediate ages. By default, the color is scaled over the
822 full range of ages, such that the oldest changes are blue, and the
823 newest changes are red.
825 When you give a prefix argument to this command, Emacs reads two
826 arguments using the minibuffer: the revision to display and annotate
827 (instead of the current file contents), and the time span in days the
828 color range should cover.
830 From the annotate buffer, these and other color scaling options are
831 available from the @samp{VC-Annotate} menu. In this buffer, you can
832 also use the following keys to browse the annotations of past revisions,
833 view diffs, or view log entries:
837 Annotate the previous revision, i.e.@: the revision before the one
838 currently annotated. A numeric prefix argument is a repeat count, so
839 @kbd{C-u 10 p} would take you back 10 revisions.
842 Annotate the next revision, i.e.@: the revision after the one
843 currently annotated. A numeric prefix argument is a repeat count.
846 Annotate the revision indicated by the current line.
849 Annotate the revision before the one indicated by the current line.
850 This is useful to see the state the file was in before the change on
851 the current line was made.
854 Show in a buffer the file revision indicated by the current line.
857 Display the diff between the current line's revision and the previous
858 revision. This is useful to see what the current line's revision
859 actually changed in the file.
862 Display the diff between the current line's revision and the previous
863 revision for all files in the changeset (for VC systems that support
864 changesets). This is useful to see what the current line's revision
865 actually changed in the tree.
868 Show the log of the current line's revision. This is useful to see
869 the author's description of the changes in the revision on the current
873 Annotate the working revision--the one you are editing. If you used
874 @kbd{p} and @kbd{n} to browse to other revisions, use this key to
875 return to your working revision.
878 Toggle the annotation visibility. This is useful for looking just at
879 the file contents without distraction from the annotations.
883 @subsection VC Change Log
887 Display the change history for the current fileset
888 (@code{vc-print-log}).
891 Display the change history for the current repository
892 (@code{vc-print-root-log}).
895 Display the changes that will be received with a pull operation
896 (@code{vc-log-incoming}).
899 Display the changes that will be sent by the next push operation
900 (@code{vc-log-outgoing}).
905 The command @kbd{C-x v l} (@code{vc-print-log}) displays a buffer
906 named @samp{*vc-change-log*}, showing the history of changes made to
907 the current file, including who made the changes, the dates, and the
908 log entry for each change (these are the same log entries you would
909 enter via the @samp{*vc-log*} buffer; @pxref{Log Buffer}). Point is
910 centered at the revision of the file currently being visited. With a
911 prefix argument, the command prompts for the revision to center on,
912 and the maximum number of revisions to display.
914 If you call @kbd{C-x v l} from a VC Directory buffer (@pxref{VC
915 Directory Mode}) or a Dired buffer (@pxref{Dired}), it applies to the
916 file listed on the current line.
918 @findex vc-print-root-log
919 @findex log-view-toggle-entry-display
920 @kbd{C-x v L} (@code{vc-print-root-log}) displays a
921 @samp{*vc-change-log*} buffer showing the history of the entire
922 version-controlled directory tree (RCS, SCCS, and CVS do not support
923 this feature). With a prefix argument, the command prompts for the
924 maximum number of revisions to display.
926 The @kbd{C-x v L} history is shown in a compact form, usually
927 showing only the first line of each log entry. However, you can type
928 @key{RET} (@code{log-view-toggle-entry-display}) in the
929 @samp{*vc-change-log*} buffer to reveal the entire log entry for the
930 revision at point. A second @key{RET} hides it again.
932 On a decentralized version control system, the @kbd{C-x v I}
933 (@code{vc-log-incoming}) command displays a log buffer showing the
934 changes that will be applied, the next time you run the version
935 control system's ``pull'' command to get new revisions from another
936 repository (@pxref{VC Pull}). This other repository is the default
937 one from which changes are pulled, as defined by the version control
938 system; with a prefix argument, @code{vc-log-incoming} prompts for a
939 specific repository. Similarly, @kbd{C-x v O}
940 (@code{vc-log-outgoing}) shows the changes that will be sent to
941 another repository, the next time you run the ``push'' command; with a
942 prefix argument, it prompts for a specific destination repository.
944 In the @samp{*vc-change-log*} buffer, you can use the following keys
945 to move between the logs of revisions and of files, and to examine and
946 compare past revisions (@pxref{Old Revisions}):
950 Move to the previous revision entry. (Revision entries in the log
951 buffer are usually in reverse-chronological order, so the previous
952 revision-item usually corresponds to a newer revision.) A numeric
953 prefix argument is a repeat count.
956 Move to the next revision entry. A numeric prefix argument is a
960 Move to the log of the previous file, if showing logs for a multi-file
961 VC fileset. Otherwise, just move to the beginning of the log. A
962 numeric prefix argument is a repeat count.
965 Move to the log of the next file, if showing logs for a multi-file VC
966 fileset. A numeric prefix argument is a repeat count.
969 Annotate the revision on the current line (@pxref{Old Revisions}).
972 Modify the change comment displayed at point. Note that not all VC
973 systems support modifying change comments.
976 Visit the revision indicated at the current line.
979 Display a diff between the revision at point and the next earlier
980 revision, for the specific file.
983 Display the changeset diff between the revision at point and the next
984 earlier revision. This shows the changes to all files made in that
988 In a compact-style log buffer (e.g.@: the one created by @kbd{C-x v
989 L}), toggle between showing and hiding the full log entry for the
993 @vindex vc-log-show-limit
994 Because fetching many log entries can be slow, the
995 @samp{*vc-change-log*} buffer displays no more than 2000 revisions by
996 default. The variable @code{vc-log-show-limit} specifies this limit;
997 if you set the value to zero, that removes the limit. You can also
998 increase the number of revisions shown in an existing
999 @samp{*vc-change-log*} buffer by clicking on the @samp{Show 2X
1000 entries} or @samp{Show unlimited entries} buttons at the end of the
1001 buffer. However, RCS, SCCS, and CVS do not support this feature.
1004 @subsection Undoing Version Control Actions
1008 Revert the work file(s) in the current VC fileset to the last revision
1012 @c `C-x v c' (vc-rollback) was removed, since it's RCS/SCCS specific.
1016 @vindex vc-revert-show-diff
1017 If you want to discard all the changes you have made to the current
1018 VC fileset, type @kbd{C-x v u} (@code{vc-revert-buffer}). This shows
1019 you a diff between the work file(s) and the revision from which you
1020 started editing, and asks for confirmation for discarding the changes.
1021 If you agree, the fileset is reverted. If you don't want @kbd{C-x v
1022 u} to show a diff, set the variable @code{vc-revert-show-diff} to
1023 @code{nil} (you can still view the diff directly with @kbd{C-x v =};
1024 @pxref{Old Revisions}). Note that @kbd{C-x v u} cannot be reversed
1025 with the usual undo commands (@pxref{Undo}), so use it with care.
1027 On locking-based version control systems, @kbd{C-x v u} leaves files
1028 unlocked; you must lock again to resume editing. You can also use
1029 @kbd{C-x v u} to unlock a file if you lock it and then decide not to
1032 @node VC Directory Mode
1033 @subsection VC Directory Mode
1035 @cindex VC Directory buffer
1036 The @dfn{VC Directory buffer} is a specialized buffer for viewing
1037 the version control statuses of the files in a directory tree, and
1038 performing version control operations on those files. In particular,
1039 it is used to specify multi-file VC filesets for commands like
1040 @w{@kbd{C-x v v}} to act on (@pxref{VC Directory Commands}).
1044 To use the VC Directory buffer, type @kbd{C-x v d} (@code{vc-dir}).
1045 This reads a directory name using the minibuffer, and switches to a VC
1046 Directory buffer for that directory. By default, the buffer is named
1047 @samp{*vc-dir*}. Its contents are described
1052 in @ref{VC Directory Buffer}.
1055 The @code{vc-dir} command automatically detects the version control
1056 system to be used in the specified directory. In the event that more
1057 than one system is being used in the directory, you should invoke the
1058 command with a prefix argument, @kbd{C-u C-x v d}; this prompts for
1059 the version control system which the VC Directory buffer should use.
1064 @cindex CVS directory mode
1065 In addition to the VC Directory buffer, Emacs has a similar facility
1066 called PCL-CVS which is specialized for CVS. @xref{Top, , About
1067 PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}.
1071 * Buffer: VC Directory Buffer. What the buffer looks like and means.
1072 * Commands: VC Directory Commands. Commands to use in a VC directory buffer.
1075 @node VC Directory Buffer
1076 @subsubsection The VC Directory Buffer
1078 The VC Directory buffer contains a list of version-controlled files
1079 and their version control statuses. It lists files in the current
1080 directory (the one specified when you called @kbd{C-x v d}) and its
1081 subdirectories, but only those with a ``noteworthy'' status. Files
1082 that are up-to-date (i.e.@: the same as in the repository) are
1083 omitted. If all the files in a subdirectory are up-to-date, the
1084 subdirectory is not listed either. As an exception, if a file has
1085 become up-to-date as a direct result of a VC command, it is listed.
1087 Here is an example of a VC Directory buffer listing:
1094 unregistered temp.txt
1101 Two work files have been modified but not committed:
1102 @file{configure.ac} in the current directory, and @file{foo.c} in the
1103 @file{src/} subdirectory. The file named @file{README} has been added
1104 but is not yet committed, while @file{temp.txt} is not under version
1105 control (@pxref{Registering}).
1107 The @samp{*} characters next to the entries for @file{README} and
1108 @file{src/main.c} indicate that the user has marked out these files as
1109 the current VC fileset
1114 (@pxref{VC Directory Commands}).
1117 The above example is typical for a decentralized version control
1118 system like Bazaar, Git, or Mercurial. Other systems can show other
1119 statuses. For instance, CVS shows the @samp{needs-update} status if
1120 the repository has changes that have not been applied to the work
1121 file. RCS and SCCS show the name of the user locking a file as its
1125 @vindex vc-stay-local
1126 @vindex vc-cvs-stay-local
1127 On CVS and Subversion, the @code{vc-dir} command normally contacts
1128 the repository, which may be on a remote machine, to check for
1129 updates. If you change the variable @code{vc-stay-local} or
1130 @code{vc-cvs-stay-local} (for CVS) to @code{nil} (@pxref{CVS
1131 Options}), then Emacs avoids contacting a remote repository when
1132 generating the VC Directory buffer (it will still contact it when
1133 necessary, e.g.@: when doing a commit). This may be desirable if you
1134 are working offline or the network is slow.
1137 @vindex vc-directory-exclusion-list
1138 The VC Directory buffer omits subdirectories listed in the variable
1139 @code{vc-directory-exclusion-list}. Its default value contains
1140 directories that are used internally by version control systems.
1142 @node VC Directory Commands
1143 @subsubsection VC Directory Commands
1145 Emacs provides several commands for navigating the VC Directory
1146 buffer, and for ``marking'' files as belonging to the current VC
1152 Move point to the next entry (@code{vc-dir-next-line}).
1155 Move point to the previous entry (@code{vc-dir-previous-line}).
1158 Move to the next directory entry (@code{vc-dir-next-directory}).
1161 Move to the previous directory entry
1162 (@code{vc-dir-previous-directory}).
1166 Visit the file or directory listed on the current line
1167 (@code{vc-dir-find-file}).
1170 Visit the file or directory on the current line, in a separate window
1171 (@code{vc-dir-find-file-other-window}).
1174 Mark the file or directory on the current line (@code{vc-dir-mark}),
1175 putting it in the current VC fileset. If the region is active, mark
1176 all files in the region.
1178 A file cannot be marked with this command if it is already in a marked
1179 directory, or one of its subdirectories. Similarly, a directory
1180 cannot be marked with this command if any file in its tree is marked.
1183 If point is on a file entry, mark all files with the same status; if
1184 point is on a directory entry, mark all files in that directory tree
1185 (@code{vc-dir-mark-all-files}). With a prefix argument, mark all
1186 listed files and directories.
1188 @kindex q @r{(VC Directory)}
1191 Bury the VC Directory buffer, and delete its window if the window was
1192 created just for that buffer.
1195 Unmark the file or directory on the current line. If the region is
1196 active, unmark all the files in the region (@code{vc-dir-unmark}).
1199 If point is on a file entry, unmark all files with the same status; if
1200 point is on a directory entry, unmark all files in that directory tree
1201 (@code{vc-dir-unmark-all-files}). With a prefix argument, unmark all
1202 files and directories.
1205 Hide files with @samp{up-to-date} status
1206 (@code{vc-dir-hide-up-to-date}).
1209 Quit the VC Directory buffer, and bury it (@code{quit-window}).
1213 @findex vc-dir-mark-all-files
1214 While in the VC Directory buffer, all the files that you mark with
1215 @kbd{m} (@code{vc-dir-mark}) or @kbd{M} (@code{vc-dir-mark}) are in
1216 the current VC fileset. If you mark a directory entry with @kbd{m},
1217 all the listed files in that directory tree are in the current VC
1218 fileset. The files and directories that belong to the current VC
1219 fileset are indicated with a @samp{*} character in the VC Directory
1220 buffer, next to their VC status. In this way, you can set up a
1221 multi-file VC fileset to be acted on by VC commands like @w{@kbd{C-x v
1222 v}} (@pxref{Basic VC Editing}), @w{@kbd{C-x v =}} (@pxref{Old
1223 Revisions}), and @w{@kbd{C-x v u}} (@pxref{VC Undo}).
1225 The VC Directory buffer also defines some single-key shortcuts for
1226 VC commands with the @kbd{C-x v} prefix: @kbd{=}, @kbd{+}, @kbd{l},
1227 @kbd{i}, and @kbd{v}.
1229 For example, you can commit a set of edited files by opening a VC
1230 Directory buffer, where the files are listed with the @samp{edited}
1231 status; marking the files; and typing @kbd{v} or @kbd{C-x v v}
1232 (@code{vc-next-action}). If the version control system is
1233 changeset-based, Emacs will commit the files in a single revision.
1235 While in the VC Directory buffer, you can also perform search and
1236 replace on the current VC fileset, with the following commands:
1240 Search the fileset (@code{vc-dir-search}).
1243 Do a regular expression query replace on the fileset
1244 (@code{vc-dir-query-replace-regexp}).
1247 Do an incremental search on the fileset (@code{vc-dir-isearch}).
1250 Do an incremental regular expression search on the fileset
1251 (@code{vc-dir-isearch-regexp}).
1255 Apart from acting on multiple files, these commands behave much like
1256 their single-buffer counterparts (@pxref{Search}).
1258 @cindex stashes in version control
1259 @cindex shelves in version control
1260 The above commands are also available via the menu bar, and via a
1261 context menu invoked by @kbd{Mouse-2}. Furthermore, some VC backends
1262 use the menu to provide extra backend-specific commands. For example,
1263 Git and Bazaar allow you to manipulate @dfn{stashes} and @dfn{shelves}
1264 (where are a way to temporarily put aside uncommitted changes, and
1265 bring them back at a later time).
1268 @subsection Version Control Branches
1269 @cindex branch (version control)
1271 One use of version control is to support multiple independent lines
1272 of development, which are called @dfn{branches}. Branches are used
1273 for maintaining separate ``stable'' and ``development'' versions of a
1274 program, and for developing unrelated features in isolation from one
1277 VC's support for branch operations is currently fairly limited. For
1278 decentralized version control systems, it provides commands for
1279 @dfn{updating} one branch with the contents of another, and for
1280 @dfn{merging} the changes made to two different branches
1281 (@pxref{Merging}). For centralized version control systems, it
1282 supports checking out different branches and committing into new or
1286 * Switching Branches:: How to get to another existing branch.
1287 * VC Pull:: Updating the contents of a branch.
1288 * Merging:: Transferring changes between branches.
1289 * Creating Branches:: How to start a new branch.
1292 @node Switching Branches
1293 @subsubsection Switching between Branches
1295 The various version control systems differ in how branches are
1296 implemented, and these differences cannot be entirely concealed by VC.
1298 On some decentralized version control systems, including Bazaar and
1299 Mercurial in its normal mode of operation, each branch has its own
1300 working directory tree, so switching between branches just involves
1301 switching directories. On Git, switching between branches is done
1302 using the @command{git branch} command, which changes the contents of
1303 the working tree itself.
1305 On centralized version control systems, you can switch between
1306 branches by typing @kbd{C-u C-x v v} in an up-to-date work file
1307 (@pxref{Advanced C-x v v}), and entering the revision ID for a
1308 revision on another branch. On CVS, for instance, revisions on the
1309 @dfn{trunk} (the main line of development) normally have IDs of the
1310 form 1.1, 1.2, 1.3, @dots{}, while the first branch created from (say)
1311 revision 1.2 has revision IDs 1.2.1.1, 1.2.1.2, @dots{}, the second
1312 branch created from revision 1.2 has revision IDs 1.2.2.1, 1.2.2.2,
1313 @dots{}, and so forth. You can also specify the @dfn{branch ID},
1314 which is a branch revision ID omitting its final component
1315 (e.g.@: 1.2.1), to switch to the latest revision on that branch.
1317 On a locking-based system, switching to a different branch also
1318 unlocks (write-protects) the working tree.
1320 Once you have switched to a branch, VC commands will apply to that
1321 branch until you switch away; for instance, any VC filesets that you
1322 commit will be committed to that specific branch.
1325 @subsubsection Pulling Changes into a Branch
1329 On a decentralized version control system, update the current branch
1330 by ``pulling in'' changes from another location.
1332 On a centralized version control system, update the current VC
1338 On a decentralized version control system, the command @kbd{C-x v +}
1339 (@code{vc-pull}) updates the current branch and working tree. It is
1340 typically used to update a copy of a remote branch. If you supply a
1341 prefix argument, the command prompts for the exact version control
1342 command to use, which lets you specify where to pull changes from.
1343 Otherwise, it pulls from a default location determined by the version
1346 Amongst decentralized version control systems, @kbd{C-x v +} is
1347 currently supported only by Bazaar, Git, and Mercurial. On Bazaar, it
1348 calls @command{bzr pull} for ordinary branches (to pull from a master
1349 branch into a mirroring branch), and @command{bzr update} for a bound
1350 branch (to pull from a central repository). On Git, it calls
1351 @command{git pull} to fetch changes from a remote repository and merge
1352 it into the current branch. On Mercurial, it calls @command{hg pull
1353 -u} to fetch changesets from the default remote repository and update
1354 the working directory.
1356 Prior to pulling, you can use @kbd{C-x v I} (@code{vc-log-incoming})
1357 to view a log buffer of the changes to be applied. @xref{VC Change
1360 On a centralized version control system like CVS, @kbd{C-x v +}
1361 updates the current VC fileset from the repository.
1364 @subsubsection Merging Branches
1365 @cindex merging changes
1369 On a decentralized version control system, merge changes from another
1370 branch into the current one.
1372 On a centralized version control system, merge changes from another
1373 branch into the current VC fileset.
1376 While developing a branch, you may sometimes need to @dfn{merge} in
1377 changes that have already been made in another branch. This is not a
1378 trivial operation, as overlapping changes may have been made to the
1381 On a decentralized version control system, merging is done with the
1382 command @kbd{C-x v m} (@code{vc-merge}). On Bazaar, this prompts for
1383 the exact arguments to pass to @command{bzr merge}, offering a
1384 sensible default if possible. On Git, this prompts for the name of a
1385 branch to merge from, with completion (based on the branch names known
1386 to the current repository). The output from running the merge command
1387 is shown in a separate buffer.
1389 On a centralized version control system like CVS, @kbd{C-x v m}
1390 prompts for a branch ID, or a pair of revision IDs (@pxref{Switching
1391 Branches}); then it finds the changes from that branch, or the changes
1392 between the two revisions you specified, and merges those changes into
1393 the current VC fileset. If you just type @key{RET}, Emacs simply
1394 merges any changes that were made on the same branch since you checked
1398 @cindex resolving conflicts
1399 Immediately after performing a merge, only the working tree is
1400 modified, and you can review the changes produced by the merge with
1401 @kbd{C-x v D} and related commands (@pxref{Old Revisions}). If the
1402 two branches contained overlapping changes, merging produces a
1403 @dfn{conflict}; a warning appears in the output of the merge command,
1404 and @dfn{conflict markers} are inserted into each affected work file,
1405 surrounding the two sets of conflicting changes. You must then
1406 resolve the conflict by editing the conflicted files. Once you are
1407 done, the modified files must be committed in the usual way for the
1408 merge to take effect (@pxref{Basic VC Editing}).
1410 @node Creating Branches
1411 @subsubsection Creating New Branches
1413 On centralized version control systems like CVS, Emacs supports
1414 creating new branches as part of a commit operation. When committing
1415 a modified VC fileset, type @kbd{C-u C-x v v} (@code{vc-next-action}
1416 with a prefix argument; @pxref{Advanced C-x v v}). Then Emacs prompts
1417 for a revision ID for the new revision. You should specify a suitable
1418 branch ID for a branch starting at the current revision. For example,
1419 if the current revision is 2.5, the branch ID should be 2.5.1, 2.5.2,
1420 and so on, depending on the number of existing branches at that point.
1422 To create a new branch at an older revision (one that is no longer
1423 the head of a branch), first select that revision (@pxref{Switching
1424 Branches}). Your procedure will then differ depending on whether you
1425 are using a locking or merging-based VCS.
1427 On a locking VCS, you will need to lock the old revision branch with
1428 @kbd{C-x v v}. You'll be asked to confirm, when you lock the old
1429 revision, that you really mean to create a new branch---if you say no,
1430 you'll be offered a chance to lock the latest revision instead. On a
1431 merging-based VCS you will skip this step.
1433 Then make your changes and type @kbd{C-x v v} again to commit a new
1434 revision. This creates a new branch starting from the selected
1437 After the branch is created, subsequent commits create new revisions
1438 on that branch. To leave the branch, you must explicitly select a
1439 different revision with @kbd{C-u C-x v v}.
1442 @include vc1-xtra.texi
1446 @section Change Logs
1449 Many software projects keep a @dfn{change log}. This is a file,
1450 normally named @file{ChangeLog}, containing a chronological record of
1451 when and how the program was changed. Sometimes, there are several
1452 change log files, each recording the changes in one directory or
1456 * Change Log Commands:: Commands for editing change log files.
1457 * Format of ChangeLog:: What the change log file looks like.
1460 @node Change Log Commands
1461 @subsection Change Log Commands
1464 @findex add-change-log-entry-other-window
1465 The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
1466 file for the file you are editing
1467 (@code{add-change-log-entry-other-window}). If that file is actually
1468 a backup file, it makes an entry appropriate for the file's
1469 parent---that is useful for making log entries for functions that
1470 have been deleted in the current version.
1472 @kbd{C-x 4 a} visits the change log file and creates a new entry
1473 unless the most recent entry is for today's date and your name. It
1474 also creates a new item for the current file. For many languages, it
1475 can even guess the name of the function or other object that was
1478 @vindex add-log-keep-changes-together
1479 When the variable @code{add-log-keep-changes-together} is
1480 non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file
1481 rather than starting a new item.
1483 You can combine multiple changes of the same nature. If you don't
1484 enter any text after the initial @kbd{C-x 4 a}, any subsequent
1485 @kbd{C-x 4 a} adds another symbol to the change log entry.
1487 @vindex add-log-always-start-new-record
1488 If @code{add-log-always-start-new-record} is non-@code{nil},
1489 @kbd{C-x 4 a} always makes a new entry, even if the last entry
1490 was made by you and on the same date.
1492 @vindex change-log-version-info-enabled
1493 @vindex change-log-version-number-regexp-list
1494 @cindex file version in change log entries
1495 If the value of the variable @code{change-log-version-info-enabled}
1496 is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the
1497 change log entry. It finds the version number by searching the first
1498 ten percent of the file, using regular expressions from the variable
1499 @code{change-log-version-number-regexp-list}.
1501 @cindex Change Log mode
1502 @findex change-log-mode
1503 The change log file is visited in Change Log mode. In this major
1504 mode, each bunch of grouped items counts as one paragraph, and each
1505 entry is considered a page. This facilitates editing the entries.
1506 @kbd{C-j} and auto-fill indent each new line like the previous line;
1507 this is convenient for entering the contents of an entry.
1509 You can use the @code{next-error} command (by default bound to
1510 @kbd{C-x `}) to move between entries in the Change Log, when Change
1511 Log mode is on. You will jump to the actual site in the file that was
1512 changed, not just to the next Change Log entry. You can also use
1513 @code{previous-error} to move back in the same list.
1515 @findex change-log-merge
1516 You can use the command @kbd{M-x change-log-merge} to merge other
1517 log files into a buffer in Change Log Mode, preserving the date
1518 ordering of entries.
1520 Version control systems are another way to keep track of changes in
1521 your program and keep a change log. In the VC log buffer, typing
1522 @kbd{C-c C-a} (@code{log-edit-insert-changelog}) inserts the relevant
1523 Change Log entry, if one exists. @xref{Log Buffer}.
1525 @node Format of ChangeLog
1526 @subsection Format of ChangeLog
1528 A change log entry starts with a header line that contains the
1529 current date, your name (taken from the variable
1530 @code{add-log-full-name}), and your email address (taken from the
1531 variable @code{add-log-mailing-address}). Aside from these header
1532 lines, every line in the change log starts with a space or a tab. The
1533 bulk of the entry consists of @dfn{items}, each of which starts with a
1534 line starting with whitespace and a star. Here are two entries, both
1535 dated in May 1993, with two items and one item respectively.
1541 1993-05-25 Richard Stallman <rms@@gnu.org>
1543 * man.el: Rename symbols `man-*' to `Man-*'.
1544 (manual-entry): Make prompt string clearer.
1546 * simple.el (blink-matching-paren-distance):
1547 Change default to 12,000.
1549 1993-05-24 Richard Stallman <rms@@gnu.org>
1551 * vc.el (minor-mode-map-alist): Don't use it if it's void.
1552 (vc-cancel-version): Doc fix.
1555 One entry can describe several changes; each change should have its
1556 own item, or its own line in an item. Normally there should be a
1557 blank line between items. When items are related (parts of the same
1558 change, in different places), group them by leaving no blank line
1561 You should put a copyright notice and permission notice at the
1562 end of the change log file. Here is an example:
1565 Copyright 1997, 1998 Free Software Foundation, Inc.
1566 Copying and distribution of this file, with or without modification, are
1567 permitted provided the copyright notice and this notice are preserved.
1571 Of course, you should substitute the proper years and copyright holder.
1574 @section Tags Tables
1575 @cindex tags and tag tables
1577 A @dfn{tag} is a reference to a subunit in a program or in a
1578 document. In source code, tags reference syntactic elements of the
1579 program: functions, subroutines, data types, macros, etc. In a
1580 document, tags reference chapters, sections, appendices, etc. Each
1581 tag specifies the name of the file where the corresponding subunit is
1582 defined, and the position of the subunit's definition in that file.
1584 A @dfn{tags table} records the tags extracted by scanning the source
1585 code of a certain program or a certain document. Tags extracted from
1586 generated files reference the original files, rather than the
1587 generated files that were scanned during tag extraction. Examples of
1588 generated files include C files generated from Cweb source files, from
1589 a Yacc parser, or from Lex scanner definitions; @file{.i} preprocessed
1590 C files; and Fortran files produced by preprocessing @file{.fpp}
1594 To produce a tags table, you run the @command{etags} shell command
1595 on a document or the source code file. The @samp{etags} program
1596 writes the tags to a @dfn{tags table file}, or @dfn{tags file} in
1597 short. The conventional name for a tags file is @file{TAGS}.
1598 @xref{Create Tags Table}.
1600 Emacs provides many commands for searching and replacing using the
1601 information recorded in tags tables. For instance, the @kbd{M-.}
1602 (@code{find-tag}) jumps to the location of a specified function
1603 definition in its source file. @xref{Find Tag}.
1605 @cindex C++ class browser, tags
1607 @cindex class browser, C++
1609 The Ebrowse facility is similar to @command{etags} but specifically
1610 tailored for C++. @xref{Top,, Ebrowse, ebrowse, Ebrowse User's
1611 Manual}. The Semantic package provides another way to generate and
1612 use tags, separate from the @command{etags} facility.
1616 * Tag Syntax:: Tag syntax for various types of code and text files.
1617 * Create Tags Table:: Creating a tags table with @command{etags}.
1618 * Etags Regexps:: Create arbitrary tags using regular expressions.
1619 * Select Tags Table:: How to visit a tags table.
1620 * Find Tag:: Commands to find the definition of a specific tag.
1621 * Tags Search:: Using a tags table for searching and replacing.
1622 * List Tags:: Using tags for completion, and listing them.
1626 @subsection Source File Tag Syntax
1628 Here is how tag syntax is defined for the most popular languages:
1632 In C code, any C function or typedef is a tag, and so are definitions of
1633 @code{struct}, @code{union} and @code{enum}.
1634 @code{#define} macro definitions, @code{#undef} and @code{enum}
1636 tags, unless you specify @samp{--no-defines} when making the tags table.
1637 Similarly, global variables are tags, unless you specify
1638 @samp{--no-globals}, and so are struct members, unless you specify
1639 @samp{--no-members}. Use of @samp{--no-globals}, @samp{--no-defines}
1640 and @samp{--no-members} can make the tags table file much smaller.
1642 You can tag function declarations and external variables in addition
1643 to function definitions by giving the @samp{--declarations} option to
1647 In C++ code, in addition to all the tag constructs of C code, member
1648 functions are also recognized; member variables are also recognized,
1649 unless you use the @samp{--no-members} option. Tags for variables and
1650 functions in classes are named @samp{@var{class}::@var{variable}} and
1651 @samp{@var{class}::@var{function}}. @code{operator} definitions have
1652 tag names like @samp{operator+}.
1655 In Java code, tags include all the constructs recognized in C++, plus
1656 the @code{interface}, @code{extends} and @code{implements} constructs.
1657 Tags for variables and functions in classes are named
1658 @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
1661 In La@TeX{} documents, the arguments for @code{\chapter},
1662 @code{\section}, @code{\subsection}, @code{\subsubsection},
1663 @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite},
1664 @code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry},
1665 @code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand},
1666 @code{\newenvironment} and @code{\renewenvironment} are tags.
1668 Other commands can make tags as well, if you specify them in the
1669 environment variable @env{TEXTAGS} before invoking @command{etags}. The
1670 value of this environment variable should be a colon-separated list of
1671 command names. For example,
1674 TEXTAGS="mycommand:myothercommand"
1679 specifies (using Bourne shell syntax) that the commands
1680 @samp{\mycommand} and @samp{\myothercommand} also define tags.
1683 In Lisp code, any function defined with @code{defun}, any variable
1684 defined with @code{defvar} or @code{defconst}, and in general the first
1685 argument of any expression that starts with @samp{(def} in column zero is
1689 In Scheme code, tags include anything defined with @code{def} or with a
1690 construct whose name starts with @samp{def}. They also include variables
1691 set with @code{set!} at top level in the file.
1694 Several other languages are also supported:
1699 In Ada code, functions, procedures, packages, tasks and types are
1700 tags. Use the @samp{--packages-only} option to create tags for
1703 In Ada, the same name can be used for different kinds of entity
1704 (e.g.@:, for a procedure and for a function). Also, for things like
1705 packages, procedures and functions, there is the spec (i.e.@: the
1706 interface) and the body (i.e.@: the implementation). To make it
1707 easier to pick the definition you want, Ada tag name have suffixes
1708 indicating the type of entity:
1725 Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
1726 directly to the body of the package @code{bidule}, while @kbd{M-x
1727 find-tag @key{RET} bidule @key{RET}} will just search for any tag
1731 In assembler code, labels appearing at the beginning of a line,
1732 followed by a colon, are tags.
1735 In Bison or Yacc input files, each rule defines as a tag the nonterminal
1736 it constructs. The portions of the file that contain C code are parsed
1740 In Cobol code, tags are paragraph names; that is, any word starting in
1741 column 8 and followed by a period.
1744 In Erlang code, the tags are the functions, records and macros defined
1748 In Fortran code, functions, subroutines and block data are tags.
1751 In HTML input files, the tags are the @code{title} and the @code{h1},
1752 @code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchors
1753 and all occurrences of @code{id=}.
1756 In Lua input files, all functions are tags.
1759 In makefiles, targets are tags; additionally, variables are tags
1760 unless you specify @samp{--no-globals}.
1763 In Objective C code, tags include Objective C definitions for classes,
1764 class categories, methods and protocols. Tags for variables and
1765 functions in classes are named @samp{@var{class}::@var{variable}} and
1766 @samp{@var{class}::@var{function}}.
1769 In Pascal code, the tags are the functions and procedures defined in
1773 In Perl code, the tags are the packages, subroutines and variables
1774 defined by the @code{package}, @code{sub}, @code{my} and @code{local}
1775 keywords. Use @samp{--globals} if you want to tag global variables.
1776 Tags for subroutines are named @samp{@var{package}::@var{sub}}. The
1777 name for subroutines defined in the default package is
1778 @samp{main::@var{sub}}.
1781 In PHP code, tags are functions, classes and defines. Vars are tags
1782 too, unless you use the @samp{--no-members} option.
1785 In PostScript code, the tags are the functions.
1788 In Prolog code, tags are predicates and rules at the beginning of
1792 In Python code, @code{def} or @code{class} at the beginning of a line
1796 You can also generate tags based on regexp matching (@pxref{Etags
1797 Regexps}) to handle other formats and languages.
1799 @node Create Tags Table
1800 @subsection Creating Tags Tables
1801 @cindex @command{etags} program
1803 The @command{etags} program is used to create a tags table file. It knows
1804 the syntax of several languages, as described in
1806 the previous section.
1811 Here is how to run @command{etags}:
1814 etags @var{inputfiles}@dots{}
1818 The @command{etags} program reads the specified files, and writes a tags
1819 table named @file{TAGS} in the current working directory. You can
1820 optionally specify a different file name for the tags table by using the
1821 @samp{--output=@var{file}} option; specifying @file{-} as a file name
1822 prints the tags table to standard output.
1824 If the specified files don't exist, @command{etags} looks for
1825 compressed versions of them and uncompresses them to read them. Under
1826 MS-DOS, @command{etags} also looks for file names like @file{mycode.cgz}
1827 if it is given @samp{mycode.c} on the command line and @file{mycode.c}
1830 If the tags table becomes outdated due to changes in the files
1831 described in it, you can update it by running the @command{etags}
1832 program again. If the tags table does not record a tag, or records it
1833 for the wrong file, then Emacs will not be able to find that
1834 definition until you update the tags table. But if the position
1835 recorded in the tags table becomes a little bit wrong (due to other
1836 editing), Emacs will still be able to find the right position, with a
1839 Thus, there is no need to update the tags table after each edit.
1840 You should update a tags table when you define new tags that you want
1841 to have listed, or when you move tag definitions from one file to
1842 another, or when changes become substantial.
1844 You can make a tags table @dfn{include} another tags table, by
1845 passing the @samp{--include=@var{file}} option to @command{etags}. It
1846 then covers all the files covered by the included tags file, as well
1849 If you specify the source files with relative file names when you run
1850 @command{etags}, the tags file will contain file names relative to the
1851 directory where the tags file was initially written. This way, you can
1852 move an entire directory tree containing both the tags file and the
1853 source files, and the tags file will still refer correctly to the source
1854 files. If the tags file is @file{-} or is in the @file{/dev} directory,
1855 however, the file names are
1856 made relative to the current working directory. This is useful, for
1857 example, when writing the tags to @file{/dev/stdout}.
1859 When using a relative file name, it should not be a symbolic link
1860 pointing to a tags file in a different directory, because this would
1861 generally render the file names invalid.
1863 If you specify absolute file names as arguments to @command{etags}, then
1864 the tags file will contain absolute file names. This way, the tags file
1865 will still refer to the same files even if you move it, as long as the
1866 source files remain in the same place. Absolute file names start with
1867 @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
1869 When you want to make a tags table from a great number of files,
1870 you may have problems listing them on the command line, because some
1871 systems have a limit on its length. You can circumvent this limit by
1872 telling @command{etags} to read the file names from its standard
1873 input, by typing a dash in place of the file names, like this:
1876 find . -name "*.[chCH]" -print | etags -
1879 @command{etags} recognizes the language used in an input file based
1880 on its file name and contents. You can specify the language
1881 explicitly with the @samp{--language=@var{name}} option. You can
1882 intermix these options with file names; each one applies to the file
1883 names that follow it. Specify @samp{--language=auto} to tell
1884 @command{etags} to resume guessing the language from the file names
1885 and file contents. Specify @samp{--language=none} to turn off
1886 language-specific processing entirely; then @command{etags} recognizes
1887 tags by regexp matching alone (@pxref{Etags Regexps}).
1889 The option @samp{--parse-stdin=@var{file}} is mostly useful when
1890 calling @command{etags} from programs. It can be used (only once) in
1891 place of a file name on the command line. @command{etags} will read from
1892 standard input and mark the produced tags as belonging to the file
1895 @samp{etags --help} outputs the list of the languages @command{etags}
1896 knows, and the file name rules for guessing the language. It also prints
1897 a list of all the available @command{etags} options, together with a short
1898 explanation. If followed by one or more @samp{--language=@var{lang}}
1899 options, it outputs detailed information about how tags are generated for
1903 @subsection Etags Regexps
1905 The @samp{--regex} option to @command{etags} allows tags to be
1906 recognized by regular expression matching. You can intermix this
1907 option with file names; each one applies to the source files that
1908 follow it. If you specify multiple @samp{--regex} options, all of
1909 them are used in parallel. The syntax is:
1912 --regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers}
1916 The essential part of the option value is @var{tagregexp}, the regexp
1917 for matching tags. It is always used anchored, that is, it only
1918 matches at the beginning of a line. If you want to allow indented
1919 tags, use a regexp that matches initial whitespace; start it with
1922 In these regular expressions, @samp{\} quotes the next character, and
1923 all the GCC character escape sequences are supported (@samp{\a} for
1924 bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for
1925 escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for
1926 carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab).
1928 Ideally, @var{tagregexp} should not match more characters than are
1929 needed to recognize what you want to tag. If the syntax requires you
1930 to write @var{tagregexp} so it matches more characters beyond the tag
1931 itself, you should add a @var{nameregexp}, to pick out just the tag.
1932 This will enable Emacs to find tags more accurately and to do
1933 completion on tag names more reliably. You can find some examples
1936 The @var{modifiers} are a sequence of zero or more characters that
1937 modify the way @command{etags} does the matching. A regexp with no
1938 modifiers is applied sequentially to each line of the input file, in a
1939 case-sensitive way. The modifiers and their meanings are:
1943 Ignore case when matching this regexp.
1945 Match this regular expression against the whole file, so that
1946 multi-line matches are possible.
1948 Match this regular expression against the whole file, and allow
1949 @samp{.} in @var{tagregexp} to match newlines.
1952 The @samp{-R} option cancels all the regexps defined by preceding
1953 @samp{--regex} options. It too applies to the file names following
1954 it. Here's an example:
1957 etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
1958 bar.ber -R --lang=lisp los.er
1962 Here @command{etags} chooses the parsing language for @file{voo.doo} and
1963 @file{bar.ber} according to their contents. @command{etags} also uses
1964 @var{reg1} to recognize additional tags in @file{voo.doo}, and both
1965 @var{reg1} and @var{reg2} to recognize additional tags in
1966 @file{bar.ber}. @var{reg1} is checked against each line of
1967 @file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while
1968 @var{reg2} is checked against the whole @file{bar.ber} file,
1969 permitting multi-line matches, in a case-sensitive way. @command{etags}
1970 uses only the Lisp tags rules, with no user-specified regexp matching,
1971 to recognize tags in @file{los.er}.
1973 You can restrict a @samp{--regex} option to match only files of a
1974 given language by using the optional prefix @var{@{language@}}.
1975 (@samp{etags --help} prints the list of languages recognized by
1976 @command{etags}.) This is particularly useful when storing many
1977 predefined regular expressions for @command{etags} in a file. The
1978 following example tags the @code{DEFVAR} macros in the Emacs source
1979 files, for the C language only:
1982 --regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
1986 When you have complex regular expressions, you can store the list of
1987 them in a file. The following option syntax instructs @command{etags} to
1988 read two files of regular expressions. The regular expressions
1989 contained in the second file are matched without regard to case.
1992 --regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file}
1996 A regex file for @command{etags} contains one regular expression per
1997 line. Empty lines, and lines beginning with space or tab are ignored.
1998 When the first character in a line is @samp{@@}, @command{etags} assumes
1999 that the rest of the line is the name of another file of regular
2000 expressions; thus, one such file can include another file. All the
2001 other lines are taken to be regular expressions. If the first
2002 non-whitespace text on the line is @samp{--}, that line is a comment.
2004 For example, we can create a file called @samp{emacs.tags} with the
2008 -- This is for GNU Emacs C source files
2009 @{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
2013 and then use it like this:
2016 etags --regex=@@emacs.tags *.[ch] */*.[ch]
2019 Here are some more examples. The regexps are quoted to protect them
2020 from shell interpretation.
2028 etags --language=none \
2029 --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
2030 --regex='/###key \(.*\)/\1/' \
2031 --regex='/[ \t]*global[ \t].*/' \
2036 Note that tags are not generated for scripts, so that you have to add
2037 a line by yourself of the form @samp{###key @var{scriptname}} if you
2044 etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
2051 etags --language=none \
2052 --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
2053 --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
2054 \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
2058 @node Select Tags Table
2059 @subsection Selecting a Tags Table
2061 @findex visit-tags-table
2062 Emacs has at any time one @dfn{selected} tags table. All the
2063 commands for working with tags tables use the selected one. To select
2064 a tags table, type @kbd{M-x visit-tags-table}, which reads the tags
2065 table file name as an argument, with @file{TAGS} in the default
2066 directory as the default.
2068 @vindex tags-file-name
2069 Emacs does not actually read in the tags table contents until you
2070 try to use them; all @code{visit-tags-table} does is store the file
2071 name in the variable @code{tags-file-name}, and setting the variable
2072 yourself is just as good. The variable's initial value is @code{nil};
2073 that value tells all the commands for working with tags tables that
2074 they must ask for a tags table file name to use.
2076 Using @code{visit-tags-table} when a tags table is already loaded
2077 gives you a choice: you can add the new tags table to the current list
2078 of tags tables, or start a new list. The tags commands use all the tags
2079 tables in the current list. If you start a new list, the new tags table
2080 is used @emph{instead} of others. If you add the new table to the
2081 current list, it is used @emph{as well as} the others.
2083 @vindex tags-table-list
2084 You can specify a precise list of tags tables by setting the variable
2085 @code{tags-table-list} to a list of strings, like this:
2087 @c keep this on two lines for formatting in smallbook
2090 (setq tags-table-list
2091 '("~/emacs" "/usr/local/lib/emacs/src"))
2096 This tells the tags commands to look at the @file{TAGS} files in your
2097 @file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
2098 directory. The order depends on which file you are in and which tags
2099 table mentions that file, as explained above.
2101 Do not set both @code{tags-file-name} and @code{tags-table-list}.
2104 @subsection Finding a Tag
2106 The most important thing that a tags table enables you to do is to find
2107 the definition of a specific tag.
2110 @item M-.@: @var{tag} @key{RET}
2111 Find first definition of @var{tag} (@code{find-tag}).
2113 Find next alternate definition of last tag specified.
2115 Go back to previous tag found.
2116 @item C-M-. @var{pattern} @key{RET}
2117 Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
2119 Find the next tag whose name matches the last pattern used.
2120 @item C-x 4 .@: @var{tag} @key{RET}
2121 Find first definition of @var{tag}, but display it in another window
2122 (@code{find-tag-other-window}).
2123 @item C-x 5 .@: @var{tag} @key{RET}
2124 Find first definition of @var{tag}, and create a new frame to select the
2125 buffer (@code{find-tag-other-frame}).
2127 Pop back to where you previously invoked @kbd{M-.} and friends.
2132 @kbd{M-.}@: (@code{find-tag}) prompts for a tag name and jumps to
2133 its source definition. It works by searching through the tags table
2134 for that tag's file and approximate character position, visiting that
2135 file, and searching for the tag definition at ever-increasing
2136 distances away from the recorded approximate position.
2138 When entering the tag argument to @kbd{M-.}, the usual minibuffer
2139 completion commands can be used (@pxref{Completion}), with the tag
2140 names in the selected tags table as completion candidates. If you
2141 specify an empty argument, the balanced expression in the buffer
2142 before or around point is the default argument. @xref{Expressions}.
2144 You don't need to give @kbd{M-.} the full name of the tag; a part
2145 will do. @kbd{M-.} finds tags which contain that argument as a
2146 substring. However, it prefers an exact match to a substring match.
2147 To find other tags that match the same substring, give @code{find-tag}
2148 a numeric argument, as in @kbd{C-u M-.} or @kbd{M-0 M-.}; this does
2149 not read a tag name, but continues searching the tags table's text for
2150 another tag containing the same substring last used.
2153 @findex find-tag-other-window
2155 @findex find-tag-other-frame
2156 Like most commands that can switch buffers, @code{find-tag} has a
2157 variant that displays the new buffer in another window, and one that
2158 makes a new frame for it. The former is @w{@kbd{C-x 4 .}}
2159 (@code{find-tag-other-window}), and the latter is @w{@kbd{C-x 5 .}}
2160 (@code{find-tag-other-frame}).
2162 To move back to previous tag definitions, use @kbd{C-u - M-.}; more
2163 generally, @kbd{M-.} with a negative numeric argument. Similarly,
2164 @w{@kbd{C-x 4 .}} with a negative argument finds the previous tag
2165 location in another window.
2168 @findex pop-tag-mark
2169 @vindex find-tag-marker-ring-length
2170 As well as going back to places you've found tags recently, you can
2171 go back to places @emph{from where} you found them, using @kbd{M-*}
2172 (@code{pop-tag-mark}). Thus you can find and examine the definition
2173 of something with @kbd{M-.} and then return to where you were with
2176 Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
2177 a depth determined by the variable @code{find-tag-marker-ring-length}.
2179 @findex find-tag-regexp
2181 The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
2182 match a specified regular expression. It is just like @kbd{M-.} except
2183 that it does regexp matching instead of substring matching.
2186 @subsection Searching and Replacing with Tags Tables
2187 @cindex search and replace in multiple files
2188 @cindex multiple-file search and replace
2190 The commands in this section visit and search all the files listed
2191 in the selected tags table, one by one. For these commands, the tags
2192 table serves only to specify a sequence of files to search. These
2193 commands scan the list of tags tables starting with the first tags
2194 table (if any) that describes the current file, proceed from there to
2195 the end of the list, and then scan from the beginning of the list
2196 until they have covered all the tables in the list.
2199 @item M-x tags-search @key{RET} @var{regexp} @key{RET}
2200 Search for @var{regexp} through the files in the selected tags
2202 @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
2203 Perform a @code{query-replace-regexp} on each file in the selected tags table.
2205 Restart one of the commands above, from the current location of point
2206 (@code{tags-loop-continue}).
2210 @kbd{M-x tags-search} reads a regexp using the minibuffer, then
2211 searches for matches in all the files in the selected tags table, one
2212 file at a time. It displays the name of the file being searched so you
2213 can follow its progress. As soon as it finds an occurrence,
2214 @code{tags-search} returns.
2217 @findex tags-loop-continue
2218 Having found one match, you probably want to find all the rest.
2219 Type @kbd{M-,} (@code{tags-loop-continue}) to resume the
2220 @code{tags-search}, finding one more match. This searches the rest of
2221 the current buffer, followed by the remaining files of the tags table.
2223 @findex tags-query-replace
2224 @kbd{M-x tags-query-replace} performs a single
2225 @code{query-replace-regexp} through all the files in the tags table. It
2226 reads a regexp to search for and a string to replace with, just like
2227 ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
2228 tags-search}, but repeatedly, processing matches according to your
2229 input. @xref{Replace}, for more information on query replace.
2231 @vindex tags-case-fold-search
2232 @cindex case-sensitivity and tags search
2233 You can control the case-sensitivity of tags search commands by
2234 customizing the value of the variable @code{tags-case-fold-search}. The
2235 default is to use the same setting as the value of
2236 @code{case-fold-search} (@pxref{Search Case}).
2238 It is possible to get through all the files in the tags table with a
2239 single invocation of @kbd{M-x tags-query-replace}. But often it is
2240 useful to exit temporarily, which you can do with any input event that
2241 has no special query replace meaning. You can resume the query
2242 replace subsequently by typing @kbd{M-,}; this command resumes the
2243 last tags search or replace command that you did. For instance, to
2244 skip the rest of the current file, you can type @kbd{M-> M-,}.
2246 The commands in this section carry out much broader searches than the
2247 @code{find-tag} family. The @code{find-tag} commands search only for
2248 definitions of tags that match your substring or regexp. The commands
2249 @code{tags-search} and @code{tags-query-replace} find every occurrence
2250 of the regexp, as ordinary search commands and replace commands do in
2253 These commands create buffers only temporarily for the files that they
2254 have to search (those which are not already visited in Emacs buffers).
2255 Buffers in which no match is found are quickly killed; the others
2258 As an alternative to @code{tags-search}, you can run @command{grep}
2259 as a subprocess and have Emacs show you the matching lines one by one.
2260 @xref{Grep Searching}.
2263 @subsection Tags Table Inquiries
2268 Perform completion on the text around point, using the selected tags
2269 table if one is loaded (@code{completion-at-point}).
2270 @item M-x list-tags @key{RET} @var{file} @key{RET}
2271 Display a list of the tags defined in the program file @var{file}.
2272 @item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
2273 Display a list of all tags matching @var{regexp}.
2276 @cindex completion (symbol names)
2277 In most programming language modes, you can type @kbd{C-M-i} or
2278 @kbd{M-@key{TAB}} (@code{completion-at-point}) to complete the symbol
2279 at point. If there is a selected tags table, this command can use it
2280 to generate completion candidates. @xref{Symbol Completion}.
2283 @kbd{M-x list-tags} reads the name of one of the files covered by
2284 the selected tags table, and displays a list of tags defined in that
2285 file. Do not include a directory as part of the file name unless the
2286 file name recorded in the tags table includes a directory.
2288 @findex tags-apropos
2289 @vindex tags-apropos-verbose
2290 @vindex tags-tag-face
2291 @vindex tags-apropos-additional-actions
2292 @kbd{M-x tags-apropos} is like @code{apropos} for tags
2293 (@pxref{Apropos}). It displays a list of tags in the selected tags
2294 table whose entries match @var{regexp}. If the variable
2295 @code{tags-apropos-verbose} is non-@code{nil}, it displays the names
2296 of the tags files together with the tag names. You can customize the
2297 appearance of the output by setting the variable @code{tags-tag-face}
2298 to a face. You can display additional output by customizing the
2299 variable @code{tags-apropos-additional-actions}; see its documentation
2303 @kbd{M-x next-file} visits files covered by the selected tags table.
2304 The first time it is called, it visits the first file covered by the
2305 table. Each subsequent call visits the next covered file, unless a
2306 prefix argument is supplied, in which case it returns to the first
2310 @section Emacs Development Environment
2311 @cindex EDE (Emacs Development Environment)
2312 @cindex Emacs Development Environment
2313 @cindex Integrated development environment
2315 EDE (@dfn{Emacs Development Environment}) is a package that simplifies
2316 the task of creating, building, and debugging large programs with
2317 Emacs. It provides some of the features of an IDE, or @dfn{Integrated
2318 Development Environment}, in Emacs.
2320 This section provides a brief description of EDE usage.
2322 For full details, see @ref{Top, EDE,, ede, Emacs Development Environment}.
2325 For full details on Ede, type @kbd{C-h i} and then select the EDE
2329 EDE is implemented as a global minor mode (@pxref{Minor Modes}). To
2330 enable it, type @kbd{M-x global-ede-mode} or click on the
2331 @samp{Project Support (EDE)} item in the @samp{Tools} menu. You can
2332 also enable EDE each time you start Emacs, by adding the following
2333 line to your initialization file:
2340 Activating EDE adds a menu named @samp{Development} to the menu bar.
2341 Many EDE commands, including the ones described below, can be invoked
2344 EDE organizes files into @dfn{projects}, which correspond to
2345 directory trees. The @dfn{project root} is the topmost directory of a
2346 project. To define a new project, visit a file in the desired project
2347 root and type @kbd{M-x ede-new}. This command prompts for a
2348 @dfn{project type}, which refers to the underlying method that EDE
2349 will use to manage the project (@pxref{Creating a Project, EDE,, ede,
2350 Emacs Development Environment}). The most common project types are
2351 @samp{Make}, which uses Makefiles, and @samp{Automake}, which uses GNU
2352 Automake (@pxref{Top, Automake,, automake, Automake}). In both cases,
2353 EDE also creates a file named @file{Project.ede}, which stores
2354 information about the project.
2356 A project may contain one or more @dfn{targets}. A target can be an
2357 object file, executable program, or some other type of file, which is
2358 ``built'' from one or more of the files in the project.
2360 To add a new @dfn{target} to a project, type @kbd{C-c . t}
2361 (@code{M-x ede-new-target}). This command also asks if you wish to
2362 ``add'' the current file to that target, which means that the target
2363 is to be built from that file. After you have defined a target, you
2364 can add more files to it by typing @kbd{C-c . a}
2365 (@code{ede-add-file}).
2367 To build a target, type @kbd{C-c . c} (@code{ede-compile-target}).
2368 To build all the targets in the project, type @kbd{C-c . C}
2369 (@code{ede-compile-project}). EDE uses the file types to guess how
2370 the target should be built.
2373 @include emerge-xtra.texi