1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
3 @c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
4 @c Free Software Foundation, Inc.
5 @c See file emacs.texi for copying conditions.
6 @node Maintaining, Abbrevs, Building, Top
7 @chapter Maintaining Large Programs
9 This chapter describes Emacs features for maintaining large
13 * Version Control:: Using version control systems.
14 * Change Log:: Maintaining a change history for your program.
15 * Tags:: Go directly to any function in your program in one
16 command. Tags remembers which file it is in.
17 * EDE:: An integrated development environment for Emacs.
19 * Emerge:: A convenient way of merging two versions of a program.
24 @section Version Control
25 @cindex version control
27 A @dfn{version control system} is a package that can record multiple
28 versions of a source file, storing information such as the creation
29 time of each version, who created it, and a description of what was
30 changed in that version.
32 The Emacs version control interface is called VC. Its commands work
33 with several different version control systems; currently, it supports
34 GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS, SCCS/CSSC, and
35 Subversion. Of these, the GNU project distributes CVS, GNU Arch, RCS,
38 VC is enabled automatically whenever you visit a file that is
39 governed by a version control system. To disable VC entirely, set the
40 customizable variable @code{vc-handled-backends} to @code{nil}
42 (@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
45 (@pxref{Customizing VC}).
49 * Introduction to VC:: How version control works in general.
50 * VC Mode Line:: How the mode line shows version control status.
51 * Basic VC Editing:: How to edit a file under version control.
52 * Old Revisions:: Examining and comparing old versions.
53 * Secondary VC Commands:: The commands used a little less frequently.
54 * VC Directory Mode:: Listing files managed by version control.
55 * Branches:: Multiple lines of development.
57 * Remote Repositories:: Efficient access to remote CVS servers.
58 * Revision Tags:: Symbolic names for revisions.
59 * Miscellaneous VC:: Various other commands and features of VC.
60 * Customizing VC:: Variables that change VC's behavior.
64 @node Introduction to VC
65 @subsection Introduction to Version Control
67 VC allows you to use a version control system from within Emacs,
68 integrating the version control operations smoothly with editing.
69 Though VC cannot completely bridge the gaps between version control
70 systems with widely differing capabilities, it does provide a uniform
71 interface to many version control operations. Regardless of which
72 version control system is in use, you will be able to do basic
73 operations in much the same way.
75 This section provides a general overview of version control, and
76 describes the version control systems that VC supports. You can skip
77 this section if you are already familiar with the version control system
81 * Why Version Control?:: Understanding the problems it addresses.
82 * Version Control Systems:: Supported version control back-end systems.
83 * VCS Concepts:: Words and concepts related to version control.
84 * Types of Log File:: The VCS log in contrast to the ChangeLog.
87 @node Why Version Control?
88 @subsubsection Understanding the problems it addresses
90 Version control systems provide you with three important
95 @dfn{Reversibility}: the ability to back up to a previous state if you
96 discover that some modification you did was a mistake or a bad idea.
99 @dfn{Concurrency}: the ability to have many people modifying the same
100 collection of files knowing that conflicting modifications can be
101 detected and resolved.
104 @dfn{History}: the ability to attach historical data to your data,
105 such as explanatory comments about the intention behind each change to
106 it. Even for a programmer working solo, change histories are an
107 important aid to memory; for a multi-person project, they are a
108 vitally important form of communication among developers.
111 @node Version Control Systems
112 @subsubsection Supported Version Control Systems
114 @cindex back end (version control)
115 VC currently works with many different version control systems or
122 SCCS was the first version control system ever built, and was long ago
123 superseded by more advanced ones. VC compensates for certain features
124 missing in SCCS (e.g., tag names for releases) by implementing them
125 itself. Other VC features, such as multiple branches, are simply
126 unavailable. Since SCCS is non-free, we recommend avoiding it.
130 CSSC is a free replacement for SCCS. You should use CSSC only if, for
131 some reason, you cannot use a more recent and better-designed version
136 RCS is the free version control system around which VC was initially
137 built. Almost everything you can do with RCS can be done through VC.
138 However, you cannot use RCS over the network, and it only works at the
139 level of individual files rather than projects.
143 CVS is the free version control system that was, until recently (circa
144 2008), used by the majority of free software projects. Nowadays, it
145 is slowly being superseded by newer systems. CVS allows concurrent
146 multi-user development either locally or over the network. It lacks
147 support for atomic commits or file moving/renaming. VC supports all
148 basic editing operations under CVS. For some less common tasks, you
149 still need to call CVS from the command line. Note also that before
150 using CVS you must set up a repository, which is a subject too complex
156 Subversion (SVN) is a free version control system designed to be
157 similar to CVS but without its problems. It supports atomic commits
158 of filesets, and versioning of directories, symbolic links, meta-data,
159 renames, copies, and deletes.
164 GNU Arch is a version control system designed for distributed work.
165 It differs in many ways from older systems like CVS and RCS. It
166 provides different methods for interoperating between users, support
167 for offline operations, and good branching and merging features. It
168 also supports atomic commits of filesets and file moving/renaming. VC
169 does not support all operations provided by GNU Arch, so you must
170 sometimes invoke it from the command line.
174 Git is a distributed version control system invented by Linus Torvalds to support
175 development of Linux (his kernel). It supports atomic commits of filesets and
176 file moving/renaming. One significant feature of git is that it
177 largely abolishes the notion of a single centralized repository;
178 instead, each working copy of a git project is its own repository and
179 coordination is done through repository-sync operations. VC supports
180 most git operations, with the exception of news merges and repository
181 syncing; these must be done from the command line.
186 Mercurial (hg) is a distributed version control system broadly
187 resembling GNU Arch and git, with atomic fileset commits and file
188 moving/renaming. Like git, it is fully decentralized. VC supports
189 most Mercurial commands, with the exception of repository sync
190 operations; this needs to be done from the command line.
195 Bazaar (bzr) is a distributed version control system that supports both
196 repository-based and distributed versioning, with atomic fileset
197 commits and file moving/renaming. VC supports most basic editing
198 operations under Bazaar.
201 Previous versions of VC supported a version control system known as
202 Meta-CVS. This support has been dropped because of limited interest
203 from users and developers.
206 @subsubsection Concepts of Version Control
209 @cindex registered file
210 When a file is under version control, we say that it is
211 @dfn{registered} in the version control system. The system has a
212 @dfn{repository} which stores both the file's present state and its
213 change history---enough to reconstruct the current version or any
214 earlier version. The repository also contains other information, such
215 as @dfn{log entries} that describe the changes made to each file.
218 @cindex checking out files
219 A file @dfn{checked out} of a repository is called the @dfn{work
220 file}. You edit the work file and make changes in it, as you would
221 with an ordinary file. After you are done with a set of changes, you
222 @dfn{check in} or @dfn{commit} the file; this records the changes in
223 the repository, along with a log entry for those changes.
227 A copy of a file stored in a repository is called a @dfn{revision}.
228 The history of a file is a sequence of revisions. Each revision is
229 named by a @dfn{revision ID}. The format of the revision ID depends
230 on the version control system; in the simplest case, it is just an
233 To go beyond these basic concepts, you will need to understand three
234 aspects in which version control systems differ.
235 They can be locking-based or merging-based; they can be file-based or
236 changeset-based; and they can be centralized or decentralized. VC
237 handles all these modes of operation, but it cannot hide the differences.
239 @cindex locking versus merging
240 A version control system typically has some mechanism to coordinate
241 between users who want to change the same file. There are two ways to
242 do this: merging and locking.
244 In a version control system that uses merging, each user may check
245 out and modify a work file at any time. The system lets you
246 @dfn{merge} your work file, which may contain changes that have not
247 been checked in, with the latest changes that others have checked into
250 Older version control systems use a @dfn{locking} scheme instead.
251 Here, work files are normally read-only. To edit a file, you ask the
252 version control system to make it writable for you by @dfn{locking}
253 it; only one user can lock a given file at any given time. This
254 procedure is analogous to, but different from, the locking that Emacs
255 uses to detect simultaneous editing of ordinary files
256 (@pxref{Interlocking}). When you check in your changes, that unlocks
257 the file, and the work file becomes read-only again. Other users may
258 then lock the file to make their own changes.
260 Both locking and merging systems can have problems when multiple
261 users try to modify the same file at the same time. Locking systems
262 have @dfn{lock conflicts}; a user may try to check a file out and be
263 unable to because it is locked. In merging systems, @dfn{merge
264 conflicts} happen when you check in a change to a file that conflicts
265 with a change checked in by someone else after your checkout. Both
266 kinds of conflict have to be resolved by human judgment and
267 communication. Experience has shown that merging is superior to
268 locking, both in convenience to developers and in minimizing the
269 number and severity of conflicts that actually occur.
271 SCCS always uses locking. RCS is lock-based by default but can be
272 told to operate in a merging style. CVS and Subversion are
273 merge-based by default but can be told to operate in a locking mode.
274 Distributed version control systems, such as GNU Arch, git, and
275 Mercurial, are exclusively merging-based.
277 VC mode supports both locking and merging version control. The
278 terms ``checkin'' and ``checkout'' come from locking-based version
279 control systems; newer version control systems have slightly different
280 operations usually called ``commit'' and ``update'', but VC hides the
281 differences between them as much as possible.
283 @cindex files versus changesets.
284 On SCCS, RCS, CVS, and other early version control systems, version
285 control operations are @dfn{file-based}: each file has its own comment
286 and revision history separate from that of all other files in the
287 system. Later systems, beginning with Subversion, are
288 @dfn{changeset-based}: a checkin may include changes to several files,
289 and the entire set of changes is treated as a unit by the system. Any
290 comment associated with the change does not belong to a single file,
291 but to the changeset itself.
293 Changeset-based version control is more flexible and powerful than
294 file-based version control; usually, when a change to multiple files
295 has to be reversed, it's good to be able to easily identify and remove
298 @cindex centralized vs. decentralized version control
299 Early version control systems were designed around a
300 @dfn{centralized} model in which each project has only one repository
301 used by all developers. SCCS, RCS, CVS, and Subversion share this
302 kind of model. One of its drawbacks is that the repository is a choke
303 point for reliability and efficiency.
305 GNU Arch pioneered the concept of @dfn{decentralized} version
306 control, later implemented in git, Mercurial, and Bazaar. A project
307 may have several different repositories, and these systems support a
308 sort of super-merge between repositories that tries to reconcile their
309 change histories. At the limit, each developer has his/her own
310 repository, and repository merges replace checkin/commit operations.
312 VC's job is to help you manage the traffic between your personal
313 workfiles and a repository. Whether that repository is a single
314 master or one of a network of peer repositories is not something VC
315 has to care about. Thus, the difference between a centralized and a
316 decentralized version control system is invisible to VC mode.
318 @node Types of Log File
319 @subsubsection Types of Log File
320 @cindex types of log file
321 @cindex log File, types of
322 @cindex version control log
324 Projects that use a version control system can have two types of log
325 for changes. One is the log maintained by the version control system:
326 each time you check in a change, you fill out a @dfn{log entry} for
327 the change (@pxref{Log Buffer}). This is called the @dfn{version
330 The other kind of log is the file @file{ChangeLog} (@pxref{Change
331 Log}). It provides a chronological record of all changes to a large
332 portion of a program---typically one directory and its subdirectories.
333 A small program would use one @file{ChangeLog} file; a large program
334 may have a @file{ChangeLog} file in each major directory.
335 @xref{Change Log}. Programmers have used change logs since long
336 before version control systems.
338 Changeset-based version systems typically maintain a changeset-based
339 modification log for the entire system, which makes change log files
340 somewhat redundant. One advantage that they retain is that it is
341 sometimes useful to be able to view the transaction history of a
342 single directory separately from those of other directories.
344 A project maintained with version control can use just the version
345 control log, or it can use both kinds of logs. It can handle some
346 files one way and some files the other way. Each project has its
347 policy, which you should follow.
349 When the policy is to use both, you typically want to write an entry
350 for each change just once, then put it into both logs. You can write
351 the entry in @file{ChangeLog}, then copy it to the log buffer with
352 @kbd{C-c C-a} when checking in the change (@pxref{Log Buffer}). Or
353 you can write the entry in the log buffer while checking in the
354 change, and later use the @kbd{C-x v a} command to copy it to
357 (@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
360 (@pxref{Change Logs and VC}).
364 @subsection Version Control and the Mode Line
365 @cindex VC, mode line indicator
367 When you visit a file that is under version control, Emacs indicates
368 this on the mode line. For example, @samp{RCS-1.3} says that the RCS
369 back end is used for that file, and the current version of the file is
372 The first part of the VC mode-line indicator is the name of the back
373 end: @samp{RCS}, @samp{CVS}, @samp{Bzr}, etc. The back-end name is
374 followed by a single character and the version of the file.
376 The character between the back-end name and the revision ID
377 indicates the version control status of the file. @samp{-} means that
378 the work file is not locked (if locking is in use), or not modified (if
379 locking is not in use). @samp{:} indicates that the file is locked, or
380 that it is modified. If the file is locked by some other user (for
381 instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
382 @samp{@@} means that the file was locally added, but not yet committed
383 to the master repository. @samp{!} indicates that the file contains
384 conflicts as result of a recent merge operation (@pxref{Merging}), or
385 that the file was removed from the version control. Finally, @samp{?}
386 means that the file is under version control, but is missing from the
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. This menu is
393 identical to the @samp{Tools / Version Control} menu item.
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
411 Most VC commands operate on @dfn{VC filesets}. A VC fileset is a
412 collection of one or more files that a VC operation acts on. When you
413 type VC commands in a buffer visiting a version-controlled file, the
414 VC fileset is simply that one file. When you type them in a VC
415 Directory buffer, and some files in it are marked, the VC fileset
416 consists of the marked files (@pxref{VC Directory Mode}).
418 The principal VC command is an all-purpose command, @kbd{C-x v v}
419 (@code{vc-next-action}), that performs either registration, locking,
420 merging or a check-in (depending on the situation) on the current VC
421 fileset. You can use @kbd{C-x v v} in a file-visiting buffer or in a
426 Perform the appropriate next version control operation on the VC fileset.
429 @findex vc-next-action
431 The precise action of @kbd{C-x v v} depends on the state of the VC
432 fileset, and whether the version control system uses locking or
433 merging. This is described in detail in the subsequent sections.
435 VC filesets are the way that VC mode bridges the gap between
436 file-based and changeset-based version control systems. They are,
437 essentially, a way to pass multiple file arguments as a group to
438 version control commands. For example, on Subversion, a checkin with
439 a multi-file VC fileset becomes a joint commit, as though you had
440 typed @command{svn commit} with those file arguments at the shell
441 command line. All files in a VC fileset must be under the same
442 version control system; if they are not, Emacs signals an error when
443 you attempt to execute a command on the fileset.
445 Support for VC filesets and changeset-based version control systems
446 is the main improvement to VC in Emacs 23. When you mark multi-file
447 VC in a VC Directory buffer, VC operations treat them as a VC fileset,
448 and operate on them all at once if the version control system is
449 changeset-based. @xref{VC Directory Mode}.
451 VC filesets are distinct from the ``named filesets'' used for
452 viewing and visiting files in functional groups (@pxref{Filesets}).
453 Unlike named filesets, VC filesets are not named and don't persist
457 * VC With A Merging VCS:: Without locking: default mode for CVS.
458 * VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS.
459 * Advanced C-x v v:: Advanced features available with a prefix argument.
460 * Log Buffer:: Features available in log entry buffers.
463 @node VC With A Merging VCS
464 @subsubsection Basic Version Control with Merging
466 When your version control system is merging-based (the default for
467 CVS and all newer version control systems), work files are always
468 writable; you need not do anything special to begin editing a file.
469 The status indicator on the mode line is @samp{-} if the file is
470 unmodified; it flips to @samp{:} as soon as you save any changes
471 (@pxref{VC Mode Line}).
473 Here is what @kbd{C-x v v} does when using a merging-based system:
477 If the work file is in a directory that is not controlled by any
478 version control system, prompt for a repository type. Then, create a
479 version control repository of that type and register the file with it.
482 If the work file is in a directory that is controlled by a version
483 control system but not registered with it, register the file.
486 If the work file is the same as in the repository, do nothing.
489 If you have not changed the work file, but some other user has checked
490 in changes to the repository, merge those changes into the work file.
493 If you have made modifications to the work file, attempts to check in
494 your changes. To do this, Emacs first reads the log entry for the new
495 revision (@pxref{Log Buffer}). If some other user has checked in
496 changes to the repository since you last checked it out, the checkin
497 fails. In that case, type @kbd{C-x v v} again to merge those changes
498 into your own work file; this puts the work file into a ``conflicted''
499 state. Type @kbd{C-x v v} to clear the ``conflicted'' state; VC then
500 regards the file as up-to-date and modified, and you can try to check
503 To pick up any recent changes from the repository @emph{without}
504 trying to commit your own changes, type @kbd{C-x v m @key{RET}}.
508 These rules also apply when you use RCS in its ``non-locking'' mode,
509 except that changes are not automatically merged from the repository.
510 Nothing informs you if another user has checked in changes in the same
511 file since you began editing it; when you check in your revision, his
512 changes are removed (however, they remain in the repository and are
513 thus not irrevocably lost). Therefore, you must verify that the
514 current revision is unchanged before checking in your changes. In
515 addition, locking is possible with RCS even in this mode: @kbd{C-x v
516 v} with an unmodified file locks the file, just as it does with RCS in
517 its normal locking mode (@pxref{VC With A Locking VCS}).
519 @node VC With A Locking VCS
520 @subsubsection Basic Version Control with Locking
522 Under a locking-based version control system (such as SCCS, and RCS
523 in its default mode), @kbd{C-x v v} does the following:
527 If the file is not locked, lock it and make it writable, so that you
531 If the file is locked by you, and contains changes, check in the
532 changes. In order to do this, Emacs first reads the log entry for the
533 new revision. @xref{Log Buffer}.
536 If the file is locked by you, but you have not changed it since you
537 locked it, release the lock and makes the file read-only again.
540 If the file is locked by some other user, ask whether you want to
541 ``steal the lock'' from that user. If you say yes, the file becomes
542 locked by you, but a message is sent to the person who had formerly
543 locked the file, to inform him of what has happened.
546 These rules also apply when you use CVS in locking mode, except
547 that there is no such thing as stealing a lock.
549 @node Advanced C-x v v
550 @subsubsection Advanced Control in @kbd{C-x v v}
552 @cindex revision ID to check in/out
553 When you give a prefix argument to @code{vc-next-action} (@kbd{C-u
554 C-x v v}), it still performs the next logical version control
555 operation, but accepts additional arguments to specify precisely how
560 If the file is modified (or locked), you can specify the revision ID
561 to use for the new version that you check in. This is one way
562 to create a new branch (@pxref{Branches}).
565 If the file is not modified (and unlocked), you can specify the
566 revision to select; this lets you start working from an older
567 revision, or on another branch. If you do not enter any revision,
568 that takes you to the highest (``head'') revision on the current
569 branch; therefore @kbd{C-u C-x v v @key{RET}} is a convenient way to
570 get the latest version of a file from the repository.
573 @cindex specific version control system
574 Instead of the revision ID, you can also specify the name of a
575 version control system. This is useful when one file is being managed
576 with two version control systems at the same time
578 (@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs
582 (@pxref{Local Version Control}).
588 @subsubsection Features of the Log Entry Buffer
590 When you check in changes, Emacs pops up a buffer called
591 @samp{*VC-Log*} for you to enter a log entry.
593 After you have finished editing the log message, type @kbd{C-c C-c}
594 to exit the buffer and commit the change.
596 @findex log-edit-show-files
597 @findex log-edit-show-diff
598 In the @samp{*VC-Log*} buffer, typing @kbd{C-c C-f}
599 (@code{log-edit-show-files}) displays a list of files in the VC
600 fileset you are committing. If you called @kbd{C-x v v} directly from
601 a work file, the VC fileset consists of that single file, so this
602 command is not very useful. If you called @kbd{C-x v v} from a VC
603 directory buffer, the VC fileset may consist of multiple files
604 (@pxref{VC Directory Mode}).
606 @findex log-edit-insert-changelog
607 Type @kbd{C-c C-d} (@code{log-edit-show-diff}) to show a ``diff'' of
608 the changes you have made (i.e., the differences between the work file
609 and the repository revision from which you started editing the file).
610 The diff is displayed in a special buffer in another window.
611 @xref{Comparing Files}.
613 If you have written an entry in the @file{ChangeLog} (@pxref{Change
614 Log}), type @kbd{C-c C-a} (@code{log-edit-insert-changelog}) to pull
615 it into the @samp{*VC-Log*} buffer. If the topmost item in the
616 @file{ChangeLog} was made under your user name on the current date,
617 this command searches that item for entries that match the file(s) to
618 be committed; if found, these entries are inserted.
620 @xref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features},
623 @xref{Change Logs and VC},
625 for the opposite way of working---generating ChangeLog entries from
626 the revision control log.
628 To abort a check-in, just @strong{don't} type @kbd{C-c C-c} in that
629 buffer. You can switch buffers and do other editing. As long as you
630 don't try to check in another file, the entry you were editing remains
631 in the @samp{*VC-Log*} buffer, and you can go back to that buffer at
632 any time to complete the check-in.
634 If you change several source files for the same reason, it is often
635 convenient to specify the same log entry for many of the files. (This
636 is the normal way to do things on a changeset-oriented system, where
637 comments are attached to changesets rather than the history of
638 individual files.) The most convenient way to do this is to mark all
639 the files in VC Directory Mode and check in from there; the log buffer
640 will carry the fileset information with it and do a group commit when
641 you type @kbd{C-c C-c}.
643 You can also browse the history of previous log entries to duplicate
644 a checkin comment. This can be useful when you want several files to
645 have checkin comments that vary only slightly from each other. The
646 commands @kbd{M-n}, @kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this
647 work just like the minibuffer history commands (except that these
648 versions are used outside the minibuffer).
650 @vindex vc-log-mode-hook
651 Each time you check in a change, the log entry buffer is put into VC
652 Log Edit mode, which involves running two hooks: @code{text-mode-hook}
653 and @code{vc-log-mode-hook}. @xref{Hooks}.
656 @subsection Examining And Comparing Old Revisions
658 One of the convenient features of version control is the ability
659 to examine any revision of a file, or compare two revisions.
663 Prompt for a revision of the current file, and visit it in a buffer of
664 its own (@code{vc-revision-other-window}).
667 Compare the files in the current fileset with the working revision(s)
668 you started from (@code{vc-diff}). With a prefix argument, prompt for
669 two revisions of the current fileset and compare them. You can call
670 this command from a Dired buffer (@pxref{Dired}).
673 Compare the entire tree corresponding to the current fileset with the
674 tree you started from (@code{vc-root-diff}). With a prefix argument,
675 prompt for two revisions and compare their trees.
678 Display an annotated version of the file: for each line, show the
679 latest revision in which it was modified (@code{vc-annotate}).
682 @findex vc-revision-other-window
684 To examine an old revision, visit the work file and type @kbd{C-x v
685 ~ @var{revision} @key{RET}} (@code{vc-revision-other-window}). Here,
686 @var{revision} is either the desired revision ID (@pxref{VCS
687 Concepts}), or the name of a tag or branch
689 (@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}).
694 This command puts the text of the old revision in a file named
695 @file{@var{filename}.~@var{revision}~}, and visits it in its own
696 buffer in a separate window.
700 @kbd{C-x v =} (@code{vc-diff}) compares each file in the current VC
701 fileset (saving them if necessary) with the repository revision(s)
702 from which you started editing. Note that the latter may or may not
703 be the latest revision of the file(s). The diff is displayed in a
704 special buffer in another window. @xref{Comparing Files}.
708 To compare two arbitrary revisions of the current VC fileset, call
709 @code{vc-diff} with a prefix argument: @kbd{C-u C-x v =}. This
710 prompts for two revision IDs, using the minibuffer, and displays the
711 diff in a special buffer in another window. Instead of providing a
712 revision ID, you can give an empty input, which specifies the current
713 contents of the work file; or a tag or branch name
715 (@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}).
720 If your version control system is file-based (e.g. CVS) rather than
721 changeset-based (Subversion, GNU Arch, git, Mercurial), supplying a
722 revision ID for a multi-file fileset (as opposed to a symbolic tag
723 name) is unlikely to return diffs that are connected in any meaningful
726 The command @kbd{C-x v D} (@code{vc-root-diff}) is similar to
727 @kbd{C-x v =}, but it compares the entire tree associated with the
728 current VC fileset with the tree you started with. This means all the
729 files controlled by the current version control repository, even those
730 that are not part of the current VC fileset.
732 If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a buffer that
733 is neither visiting a version-controlled file nor a VC directory
734 buffer, these commands generate a diff of all registered files in the
735 current directory and its subdirectories.
737 @vindex vc-diff-switches
738 @vindex vc-rcs-diff-switches
739 @kbd{C-x v =} works by running a variant of the @code{diff} utility
740 designed to work with the version control system in use. The options
741 to pass to the @code{diff} command are taken from the first non-@code{nil}
742 value of @code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches},
743 and @code{diff-switches} (@pxref{Comparing Files}), in that order.
744 Since @code{nil} means to check the next variable in the sequence,
745 either of the first two may use the value @code{t} to mean no switches at all.
746 Most of the @samp{vc@dots{}diff-switches} variables default to
747 @code{nil}, but some default to @code{t}. These are for those version
748 control systems (e.g. SVN) whose @code{diff} implementations do not
749 accept common options (e.g. @samp{-c}) likely to be in
750 @code{diff-switches}.
752 The buffer produced by @kbd{C-x v =} supports the commands of
753 Compilation mode (@pxref{Compilation Mode}), such as @kbd{C-x `} and
754 @kbd{C-c C-c}, in both the ``old'' and ``new'' text, and they always
755 find the corresponding locations in the current work file. (Older
756 revisions are not, in general, present as files on your disk.)
760 For some back ends, you can display the file @dfn{annotated} with
761 per-line revision information, by typing @kbd{C-x v g}
762 (@code{vc-annotate}). This creates a new buffer (the ``annotate
763 buffer'') displaying the file's text, with each part colored to show
764 how old it is. Text colored red is new, blue means old, and
765 intermediate colors indicate intermediate ages. By default, the color
766 is scaled over the full range of ages, such that the oldest changes
767 are blue, and the newest changes are red.
769 When you give a prefix argument to this command, Emacs reads two
770 arguments using the minibuffer: the ID of which revision to display and
771 annotate (instead of the current file contents), and the time span in
772 days the color range should cover.
774 From the annotate buffer, these and other color scaling options are
775 available from the @samp{VC-Annotate} menu. In this buffer, you can
776 also use the following keys to browse the annotations of past revisions,
777 view diffs, or view log entries:
781 Annotate the previous revision, that is to say, the revision before
782 the one currently annotated. A numeric prefix argument is a repeat
783 count, so @kbd{C-u 10 p} would take you back 10 revisions.
786 Annotate the next revision---the one after the revision currently
787 annotated. A numeric prefix argument is a repeat count.
790 Annotate the revision indicated by the current line.
793 Annotate the revision before the one indicated by the current line.
794 This is useful to see the state the file was in before the change on
795 the current line was made.
798 Show in a buffer the file revision indicated by the current line.
801 Display the diff between the current line's revision and the previous
802 revision. This is useful to see what the current line's revision
803 actually changed in the file.
806 Display the diff between the current line's revision and the previous
807 revision for all files in the changeset (for VC systems that support
808 changesets). This is useful to see what the current line's revision
809 actually changed in the tree.
812 Show the log of the current line's revision. This is useful to see
813 the author's description of the changes in the revision on the current
817 Annotate the working revision--the one you are editing. If you used
818 @kbd{p} and @kbd{n} to browse to other revisions, use this key to
819 return to your working revision.
822 Toggle the annotation visibility. This is useful for looking just at
823 the file contents without distraction from the annotations.
826 @node Secondary VC Commands
827 @subsection The Secondary Commands of VC
829 This section explains the secondary commands of VC.
832 * Registering:: Putting a file under version control.
833 * VC Change Log:: Viewing the VC Change Log.
834 * VC Undo:: Canceling changes before or after check-in.
838 @subsubsection Registering a File for Version Control
842 You can put any file under version control by simply visiting it, and
843 then typing @w{@kbd{C-x v i}} (@code{vc-register}).
847 Register the visited file for version control.
850 To register the file, Emacs must choose which version control system
851 to use for it. If the file's directory already contains files
852 registered in a version control system, Emacs uses that system. If
853 there is more than one system in use for a directory, Emacs uses the
854 one that appears first in @code{vc-handled-backends}
856 (@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
859 (@pxref{Customizing VC}).
861 On the other hand, if there are no files already registered, Emacs uses
862 the first system from @code{vc-handled-backends} that could register
863 the file (for example, you cannot register a file under CVS if its
864 directory is not already part of a CVS tree); with the default value
865 of @code{vc-handled-backends}, this means that Emacs uses RCS in this
868 If locking is in use, @kbd{C-x v i} leaves the file unlocked and
869 read-only. Type @kbd{C-x v v} if you wish to start editing it. After
870 registering a file with CVS, you must subsequently commit the initial
871 revision by typing @kbd{C-x v v}. Until you do that, the revision ID
872 appears as @samp{@@@@} in the mode line.
874 @vindex vc-default-init-revision
875 @cindex initial revision ID to register
876 The default initial revision ID for a newly registered file
877 varies by what VCS you are using; normally it will be 1.1 on VCSes
878 that use dot-pair revision IDs and 1 on VCSes that use monotonic IDs.
879 You can specify a different default by setting the variable
880 @code{vc-default-init-revision}, or you can give @kbd{C-x v i} a
881 numeric argument; then it reads the initial revision ID for this
882 particular file using the minibuffer.
884 @vindex vc-initial-comment
885 If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an
886 initial comment to describe the purpose of this source file. Reading
887 the initial comment works like reading a log entry (@pxref{Log Buffer}).
890 @subsubsection VC Change Log
894 Display revision control state and change history
895 (@code{vc-print-log}).
898 Display the change history for the current repository
899 (@code{vc-print-root-log}).
904 The command @kbd{C-x v l} (@code{vc-print-log}) displays a buffer
905 named @samp{*vc-change-log*} in a new window. This buffer lists the
906 changes to the current file, including the associated log entries.
907 (These are the log entries associated with the version control system,
908 i.e. the ones you enter via the @samp{*VC-Log*} buffer. @xref{Log
909 Buffer}.) Point is centered at the revision of the file currently
910 being visited. With a prefix argument, the command prompts for the
911 revision to center on, and the maximum number of revisions to display.
912 You can call this command from a Dired buffer (@pxref{Dired}).
914 @findex vc-print-root-log
915 Type @kbd{C-x v L} (@code{vc-print-root-log}) to display a
916 @samp{*vc-change-log*} buffer showing the history of the
917 version-controlled directory tree as a whole. With a prefix argument,
918 the command prompts for the maximum number of revisions to display.
919 RCS, SCCS, and CVS do not support this feature.
921 In the @samp{*vc-change-log*} buffer, you can use the following keys
922 to move between the logs of revisions and of files, to view past
923 revisions, to modify change comments, to view annotations and to view
928 Move to the previous revision-item in the buffer. (Revision entries in the log
929 buffer are usually in reverse-chronological order, so the previous
930 revision-item usually corresponds to a newer revision.) A numeric
931 prefix argument is a repeat count.
934 Move to the next revision-item (which most often corresponds to the
935 previous revision of the file). A numeric prefix argument is a repeat
939 Move to the log of the previous file, when the logs of multiple files
940 are in the log buffer (@pxref{VC Directory Mode}). Otherwise, just
941 move to the beginning of the log. A numeric prefix argument is a
942 repeat count, so @kbd{C-u 10 P} would move backward 10 files.
945 Move to the log of the next file, when the logs of multiple files are
946 in the log buffer (@pxref{VC Directory Mode}). It also takes a
947 numeric prefix argument as a repeat count.
950 Annotate the revision indicated by the current line.
953 Modify the change comment displayed at point. Note that not all VC
954 systems support modifying change comments.
957 Visit the revision indicated at the current line, like typing @kbd{C-x
958 v ~} and specifying this revision's ID (@pxref{Old Revisions}).
961 Display the diff (@pxref{Comparing Files}) between the revision
962 indicated at the current line and the next earlier revision. This is
963 useful to see what actually changed in the file when the revision
964 indicated on the current line was committed.
967 Display the changeset diff (@pxref{Comparing Files}) between the
968 revision indicated at the current line and the next earlier revision.
969 This is useful to see all the changes to all files that the revision
970 indicated on the current line did when it was committed.
973 @vindex vc-log-show-limit
974 Because fetching many log entries can be slow, the
975 @samp{*vc-change-log*} buffer displays no more than 2000 revisions by
976 default. The variable @code{vc-log-show-limit} specifies this limit;
977 if you set the value to zero, that removes the limit. You can also
978 increase the number of revisions shown in an existing
979 @samp{*vc-change-log*} buffer by clicking on the @samp{Show 2X
980 entries} or @samp{Show unlimited entries} buttons at the end of the
981 buffer. However, RCS, SCCS, and CVS do not support this feature.
984 @subsubsection Undoing Version Control Actions
988 Revert the buffer and the file to the working revision from which you started
992 Remove the last-entered change from the master for the visited file.
993 This undoes your last check-in.
997 @findex vc-revert-buffer
998 If you want to discard your current set of changes and revert to the
999 working revision from which you started editing the file, use @kbd{C-x
1000 v u} (@code{vc-revert-buffer}). If the version control system is
1001 locking-based, this leaves the file unlocked, and you must lock it
1002 again before making new changes. @kbd{C-x v u} requires confirmation,
1003 unless it sees that you haven't made any changes with respect to the
1004 master copy of the working revision.
1006 @kbd{C-x v u} is also the command to unlock a file if you lock it and
1007 then decide not to change it.
1011 To cancel a change that you already checked in, use @kbd{C-x v c}
1012 (@code{vc-rollback}). This command discards all record of the most
1013 recent checked-in revision, but only if your work file corresponds to
1014 that revision---you cannot use @kbd{C-x v c} to cancel a revision that
1015 is not the latest on its branch. Note that many version control
1016 systems do not support rollback at all; this command is something of a
1019 @node VC Directory Mode
1020 @subsection VC Directory Mode
1024 When you are working on a large program, it is often useful to find
1025 out which files have changed within an entire directory tree, or to
1026 view the status of all files under version control at once, and to
1027 perform version control operations on collections of files. You can
1028 use the command @kbd{C-x v d} (@code{vc-dir}) to make a directory
1029 listing that includes only files relevant for version control. This
1030 creates a @dfn{VC Directory buffer} and displays it in a separate
1035 @cindex CVS directory mode
1036 The VC Directory buffer works with all the version control systems
1037 that VC supports. For CVS, Emacs also offers a more powerful facility
1038 called PCL-CVS. @xref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The
1039 Emacs Front-End to CVS}.
1042 * Buffer: VC Directory Buffer. What the buffer looks like and means.
1043 * Commands: VC Directory Commands. Commands to use in a VC directory buffer.
1046 @node VC Directory Buffer
1047 @subsubsection The VC Directory Buffer
1049 The VC Directory buffer contains a list of version-controlled files
1050 in the current directory and its subdirectories. Files which are
1051 up-to-date (have no local differences from the repository copy) are
1052 usually hidden; if all files in a subdirectory are up-to-date, the
1053 subdirectory is hidden as well. There is an exception to this rule:
1054 if VC mode detects that a file has changed to an up-to-date state
1055 since you last looked at it, that file and its state are shown.
1057 If a directory uses more that one version control system, you can
1058 select which system to use for the @code{vc-dir} command by invoking
1059 @code{vc-dir} with a prefix argument: @kbd{C-u C-x v d}.
1061 The line for an individual file shows the version control state of
1062 the file. Under RCS and SCCS, the name of the user locking the file
1063 is shown; under CVS, an abbreviated version of the @samp{cvs status}
1064 output is used. Here is an example using CVS:
1070 needs-update file2.c
1076 In this example, @samp{file1.c} is modified with respect to the
1077 repository, and @samp{file2.c} is not. @samp{file3.c} is modified,
1078 but other changes have also been checked in to the repository---you
1079 need to merge them with the work file before you can check it in.
1081 @vindex vc-stay-local
1082 @vindex vc-cvs-stay-local
1083 In the above, if the repository were on a remote machine, VC only
1084 contacts it when the variable @code{vc-stay-local} (or
1085 @code{vc-cvs-stay-local}) is @code{nil}
1087 (@pxref{CVS Options,,,emacs-xtra, Specialized Emacs Features}).
1090 (@pxref{CVS Options}).
1092 This is because access to the repository may be slow, or you may be
1093 working offline and not have access to the repository at all. As a
1094 consequence, VC would not be able to tell you that @samp{file3.c} is
1095 in the ``merge'' state; you would learn that only when you try to
1096 check-in your modified copy of the file, or use a command such as
1099 In practice, this is not a problem because CVS handles this case
1100 consistently whenever it arises. In VC, you'll simply get prompted to
1101 merge the remote changes into your work file first. The benefits of
1102 less network communication usually outweigh the disadvantage of not
1103 seeing remote changes immediately.
1105 @vindex vc-directory-exclusion-list
1106 When a VC directory displays subdirectories it omits some that
1107 should never contain any files under version control. By default,
1108 this includes Version Control subdirectories such as @samp{RCS} and
1109 @samp{CVS}; you can customize this by setting the variable
1110 @code{vc-directory-exclusion-list}.
1112 @node VC Directory Commands
1113 @subsubsection VC Directory Commands
1115 VC Directory mode has a full set of navigation and marking commands
1116 for picking out filesets. Some of these are also available in a
1117 context menu invoked by the @kbd{mouse-2} button.
1119 Up- and down-arrow keys move in the buffer; @kbd{n} and @kbd{p} also
1120 move vertically as in other list-browsing modes. @key{SPC} and
1121 @key{TAB} behave like down-arrow, and @key{BackTab} behaves like
1124 Both @kbd{C-m} and @kbd{f} visit the file on the current
1125 line. @kbd{o} visits that file in another window. @kbd{q} dismisses
1126 the directory buffer.
1128 @kbd{x} hides up-to-date files.
1130 @kbd{m} marks the file or directory on the current line. If the
1131 region is active, @kbd{m} marks all the files in the region. There
1132 are some restrictions when marking: a file cannot be marked if any of
1133 its parent directories are marked, and a directory cannot be marked if
1134 any files in it or in its child directories are marked.
1136 @kbd{M} marks all the files with the same VC state as the current
1137 file if the cursor is on a file. If the cursor is on a directory, it
1138 marks all child files. With a prefix argument: marks all files and
1141 @kbd{u} unmarks the file or directory on the current line. If the
1142 region is active, it unmarks all the files in the region.
1144 @kbd{U} marks all the files with the same VC state as the current file
1145 if the cursor is on a file. If the cursor is on a directory, it
1146 unmarks all child files. With a prefix argument: unmarks all marked
1147 files and directories.
1149 It is possible to do search, search and replace, incremental search,
1150 and incremental regexp search on multiple files. These commands will
1151 work on all the marked files or the current file if nothing is marked.
1152 If a directory is marked, the files in that directory shown in the VC
1153 directory buffer will be used.
1155 @kbd{S} searches the marked files.
1157 @kbd{Q} does a query replace on the marked files.
1159 @kbd{M-s a C-s} does an incremental search on the marked files.
1161 @kbd{M-s a C-M-s} does an incremental search on the marked files.
1163 @cindex stashes in version control
1164 @cindex shelves in version control
1165 Commands are also accessible from the VC-dir menu. Note that some
1166 VC backends use the VC-dir menu to make available extra,
1167 backend-specific, commands. For example, Git and Bazaar allow you to
1168 manipulate @dfn{stashes} and @dfn{shelves}. (These provide a
1169 mechanism to temporarily store uncommitted changes somewhere out of
1170 the way, and bring them back at a later time.)
1172 Normal VC commands with the @kbd{C-x v} prefix work in VC directory
1173 buffers. Some single-key shortcuts are available as well; @kbd{=},
1174 @kbd{+}, @kbd{l}, @kbd{i}, and @kbd{v} behave as through prefixed with
1177 The command @kbd{C-x v v} (@code{vc-next-action}) operates on all the
1178 marked files, so that you can check in several files at once.
1179 If the underlying VC supports atomic commits of multiple-file
1180 changesets, @kbd{C-x v v} with a selected set of modified but not
1181 committed files will commit all of them at once as a single changeset.
1183 When @kbd{C-x v v} (@code{vc-next-action}) operates on multiple
1184 files, all of those files must be either in the same state or in
1185 compatible states (added, modified and removed states are considered
1186 compatible). Otherwise it signals an error. This differs from the
1187 behavior of older versions of VC, which did not have fileset
1188 operations and simply did @code{vc-next-action} on each file
1191 If any files are in a state that calls for commit, @kbd{C-x v v} reads a
1192 single log entry and uses it for the changeset as a whole. If the
1193 underling VCS is file- rather than changeset-oriented, the log entry
1194 will be replicated into the history of each file.
1197 @subsection Multiple Branches of a File
1198 @cindex branch (version control)
1199 @cindex trunk (version control)
1201 One use of version control is to maintain multiple ``current''
1202 revisions of a file. For example, you might have different revisions of a
1203 program in which you are gradually adding various unfinished new
1204 features. Each such independent line of development is called a
1205 @dfn{branch}. VC allows you to create branches, switch between
1206 different branches, and merge changes from one branch to another.
1207 Please note, however, that branches are not supported for SCCS.
1209 A file's main line of development is usually called the @dfn{trunk}.
1210 You can create multiple branches from the trunk. How the difference
1211 between trunk and branch is made visible is dependent on whether the
1212 VCS uses dot-pair or monotonic version IDs.
1214 In VCSes with dot-pair revision IDs, the revisions on the trunk are
1215 normally IDed 1.1, 1.2, 1.3, etc. At any such revision, you can
1216 start an independent branch. A branch starting at revision 1.2 would
1217 have revision ID 1.2.1.1, and consecutive revisions on this branch
1218 would have IDs 1.2.1.2, 1.2.1.3, 1.2.1.4, and so on. If there is
1219 a second branch also starting at revision 1.2, it would consist of
1220 revisions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc.
1222 In VCSes with monotonic revision IDs, trunk revisions are IDed as
1223 1, 2, 3, etc. A branch from (say) revision 2 might start with 2.1 and
1224 continue through 2.2, 2.3, etc. But naming conventions for branches
1225 and subbranches vary widely on these systems, and some (like
1226 Mercurial) never depart from the monotonic integer sequence at all.
1227 Consult the documentation of the VCS you are using.
1229 @cindex head revision
1230 If you omit the final component of a dot-pair revision ID, that is called a
1231 @dfn{branch ID}. It refers to the highest existing revision on that
1232 branch---the @dfn{head revision} of that branch. The branches in the
1233 dot-pair example above have branch IDs 1.2.1 and 1.2.2.
1236 * Switching Branches:: How to get to another existing branch.
1237 * Creating Branches:: How to start a new branch.
1238 * Merging:: Transferring changes between branches.
1239 * Multi-User Branching:: Multiple users working at multiple branches
1243 @node Switching Branches
1244 @subsubsection Switching between Branches
1246 To switch between branches, type @kbd{C-u C-x v v} and specify the
1247 revision ID you want to select. On a locking-based system, this
1248 version is then visited @emph{unlocked} (write-protected), so you can
1249 examine it before locking it. Switching branches in this way is allowed
1250 only when the file is not locked.
1252 On a VCS with dot-pair IDs, you can omit the minor part, thus giving
1253 only the branch ID; this takes you to the head version on the
1254 chosen branch. If you only type @key{RET}, Emacs goes to the highest
1255 version on the trunk.
1257 After you have switched to any branch (including the main branch), you
1258 stay on it for subsequent VC commands, until you explicitly select some
1261 @node Creating Branches
1262 @subsubsection Creating New Branches
1264 To create a new branch from a head revision (one that is the latest in
1265 the branch that contains it), first select that revision if necessary,
1266 lock it with @kbd{C-x v v}, and make whatever changes you want. Then,
1267 when you check in the changes, use @kbd{C-u C-x v v}. This lets you
1268 specify the revision ID for the new revision. You should specify a
1269 suitable branch ID for a branch starting at the current revision.
1270 For example, if the current revision is 2.5, the branch ID should be
1271 2.5.1, 2.5.2, and so on, depending on the number of existing branches at
1274 To create a new branch at an older revision (one that is no longer the
1275 head of a branch), first select that revision (@pxref{Switching
1276 Branches}). Your procedure will then differ depending on whether you
1277 are using a locking or merging-based VCS.
1279 On a locking VCS, you will need to lock the old revision branch with
1280 @kbd{C-x v v}. You'll be asked to confirm, when you lock the old
1281 revision, that you really mean to create a new branch---if you say no,
1282 you'll be offered a chance to lock the latest revision instead. On
1283 a merging-based VCS you will skip this step.
1285 Then make your changes and type @kbd{C-x v v} again to check in a new
1286 revision. This automatically creates a new branch starting from the
1287 selected revision. You need not specially request a new branch, because
1288 that's the only way to add a new revision at a point that is not the head
1291 After the branch is created, you ``stay'' on it. That means that
1292 subsequent check-ins create new revisions on that branch. To leave the
1293 branch, you must explicitly select a different revision with @kbd{C-u C-x
1294 v v}. To transfer changes from one branch to another, use the merge
1295 command, described in the next section.
1298 @subsubsection Merging Branches
1300 @cindex merging changes
1301 When you have finished the changes on a certain branch, you will
1302 often want to incorporate them into the file's main line of development
1303 (the trunk). This is not a trivial operation, because development might
1304 also have proceeded on the trunk, so that you must @dfn{merge} the
1305 changes into a file that has already been changed otherwise. VC allows
1306 you to do this (and other things) with the @code{vc-merge} command.
1309 @item C-x v m (vc-merge)
1310 Merge changes into the work file.
1315 @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it
1316 into the current version of the work file. It firsts asks you in the
1317 minibuffer where the changes should come from. If you just type
1318 @key{RET}, Emacs merges any changes that were made on the same branch
1319 since you checked the file out (we call this @dfn{merging the news}).
1320 This is the common way to pick up recent changes from the repository,
1321 regardless of whether you have already changed the file yourself.
1323 You can also enter a branch ID or a pair of revision IDs in
1324 the minibuffer. Then @kbd{C-x v m} finds the changes from that
1325 branch, or the differences between the two revisions you specified, and
1326 merges them into the current revision of the current file.
1328 As an example, suppose that you have finished a certain feature on
1329 branch 1.3.1. In the meantime, development on the trunk has proceeded
1330 to revision 1.5. To merge the changes from the branch to the trunk,
1331 first go to the head revision of the trunk, by typing @kbd{C-u C-x v v
1332 @key{RET}}. Revision 1.5 is now current. If locking is used for the file,
1333 type @kbd{C-x v v} to lock revision 1.5 so that you can change it. Next,
1334 type @kbd{C-x v m 1.3.1 @key{RET}}. This takes the entire set of changes on
1335 branch 1.3.1 (relative to revision 1.3, where the branch started, up to
1336 the last revision on the branch) and merges it into the current revision
1337 of the work file. You can now check in the changed file, thus creating
1338 revision 1.6 containing the changes from the branch.
1340 It is possible to do further editing after merging the branch, before
1341 the next check-in. But it is usually wiser to check in the merged
1342 revision, then lock it and make the further changes. This will keep
1343 a better record of the history of changes.
1346 @cindex resolving conflicts
1347 When you merge changes into a file that has itself been modified, the
1348 changes might overlap. We call this situation a @dfn{conflict}, and
1349 reconciling the conflicting changes is called @dfn{resolving a
1352 Whenever conflicts occur during merging, VC detects them, tells you
1353 about them in the echo area, and asks whether you want help in merging.
1354 If you say yes, it starts an Ediff session (@pxref{Top,
1355 Ediff, Ediff, ediff, The Ediff Manual}).
1357 If you say no, the conflicting changes are both inserted into the
1358 file, surrounded by @dfn{conflict markers}. The example below shows how
1359 a conflict region looks; the file is called @samp{name} and the current
1360 master file revision with user B's changes in it is 1.11.
1362 @c @w here is so CVS won't think this is a conflict.
1366 @var{User A's version}
1368 @var{User B's version}
1373 @cindex vc-resolve-conflicts
1374 Then you can resolve the conflicts by editing the file manually. Or
1375 you can type @code{M-x vc-resolve-conflicts} after visiting the file.
1376 This starts an Ediff session, as described above. Don't forget to
1377 check in the merged version afterwards.
1379 @node Multi-User Branching
1380 @subsubsection Multi-User Branching
1382 It is often useful for multiple developers to work simultaneously on
1383 different branches of a file. CVS and later systems allow this by
1384 default; for RCS, it is possible if you create multiple source
1385 directories. Each source directory should have a link named
1386 @file{RCS} which points to a common directory of RCS master files.
1387 Then each source directory can have its own choice of selected
1388 revisions, but all share the same common RCS records.
1390 This technique works reliably and automatically, provided that the
1391 source files contain RCS version headers
1393 (@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}).
1396 (@pxref{Version Headers}).
1398 The headers enable Emacs to be sure, at all times, which revision
1399 ID is present in the work file.
1401 If the files do not have version headers, you must instead tell Emacs
1402 explicitly in each session which branch you are working on. To do this,
1403 first find the file, then type @kbd{C-u C-x v v} and specify the correct
1404 branch ID. This ensures that Emacs knows which branch it is using
1405 during this particular editing session.
1408 @include vc1-xtra.texi
1412 @section Change Logs
1415 A change log file contains a chronological record of when and why you
1416 have changed a program, consisting of a sequence of entries describing
1417 individual changes. Normally it is kept in a file called
1418 @file{ChangeLog} in the same directory as the file you are editing, or
1419 one of its parent directories. A single @file{ChangeLog} file can
1420 record changes for all the files in its directory and all its
1424 * Change Log Commands:: Commands for editing change log files.
1425 * Format of ChangeLog:: What the change log file looks like.
1428 @node Change Log Commands
1429 @subsection Change Log Commands
1432 @findex add-change-log-entry-other-window
1433 The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
1434 file for the file you are editing
1435 (@code{add-change-log-entry-other-window}). If that file is actually
1436 a backup file, it makes an entry appropriate for the file's
1437 parent---that is useful for making log entries for functions that
1438 have been deleted in the current version.
1440 @kbd{C-x 4 a} visits the change log file and creates a new entry
1441 unless the most recent entry is for today's date and your name. It
1442 also creates a new item for the current file. For many languages, it
1443 can even guess the name of the function or other object that was
1446 @vindex add-log-keep-changes-together
1447 When the variable @code{add-log-keep-changes-together} is
1448 non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file
1449 rather than starting a new item.
1451 @vindex add-log-always-start-new-record
1452 If @code{add-log-always-start-new-record} is non-@code{nil},
1453 @kbd{C-x 4 a} always makes a new entry, even if the last entry
1454 was made by you and on the same date.
1456 @vindex change-log-version-info-enabled
1457 @vindex change-log-version-number-regexp-list
1458 @cindex file version in change log entries
1459 If the value of the variable @code{change-log-version-info-enabled}
1460 is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the
1461 change log entry. It finds the version number by searching the first
1462 ten percent of the file, using regular expressions from the variable
1463 @code{change-log-version-number-regexp-list}.
1465 @cindex Change Log mode
1466 @findex change-log-mode
1467 The change log file is visited in Change Log mode. In this major
1468 mode, each bunch of grouped items counts as one paragraph, and each
1469 entry is considered a page. This facilitates editing the entries.
1470 @kbd{C-j} and auto-fill indent each new line like the previous line;
1471 this is convenient for entering the contents of an entry.
1473 You can use the @code{next-error} command (by default bound to
1474 @kbd{C-x `}) to move between entries in the Change Log, when Change
1475 Log mode is on. You will jump to the actual site in the file that was
1476 changed, not just to the next Change Log entry. You can also use
1477 @code{previous-error} to move back in the same list.
1479 @findex change-log-merge
1480 You can use the command @kbd{M-x change-log-merge} to merge other
1481 log files into a buffer in Change Log Mode, preserving the date
1482 ordering of entries.
1484 Version control systems are another way to keep track of changes in
1485 your program and keep a change log. In the VC log buffer, typing
1486 @kbd{C-c C-a} (@code{log-edit-insert-changelog}) inserts the relevant
1487 Change Log entry, if one exists (@pxref{Log Buffer}). You can also
1488 insert a VC log entry into a Change Log buffer by typing @kbd{C-x v a}
1489 (@code{vc-update-change-log}) in the Change Log buffer
1491 (@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
1494 (@pxref{Change Logs and VC}).
1497 @node Format of ChangeLog
1498 @subsection Format of ChangeLog
1500 A change log entry starts with a header line that contains the current
1501 date, your name, and your email address (taken from the variable
1502 @code{add-log-mailing-address}). Aside from these header lines, every
1503 line in the change log starts with a space or a tab. The bulk of the
1504 entry consists of @dfn{items}, each of which starts with a line starting
1505 with whitespace and a star. Here are two entries, both dated in May
1506 1993, with two items and one item respectively.
1512 1993-05-25 Richard Stallman <rms@@gnu.org>
1514 * man.el: Rename symbols `man-*' to `Man-*'.
1515 (manual-entry): Make prompt string clearer.
1517 * simple.el (blink-matching-paren-distance):
1518 Change default to 12,000.
1520 1993-05-24 Richard Stallman <rms@@gnu.org>
1522 * vc.el (minor-mode-map-alist): Don't use it if it's void.
1523 (vc-cancel-version): Doc fix.
1526 One entry can describe several changes; each change should have its
1527 own item, or its own line in an item. Normally there should be a
1528 blank line between items. When items are related (parts of the same
1529 change, in different places), group them by leaving no blank line
1532 You should put a copyright notice and permission notice at the
1533 end of the change log file. Here is an example:
1536 Copyright 1997, 1998 Free Software Foundation, Inc.
1537 Copying and distribution of this file, with or without modification, are
1538 permitted provided the copyright notice and this notice are preserved.
1542 Of course, you should substitute the proper years and copyright holder.
1545 @section Tags Tables
1546 @cindex tags and tag tables
1548 A @dfn{tag} is a reference to a subunit in a program or in a
1549 document. In program source code, tags reference syntactic elements
1550 of the program: functions, subroutines, data types, macros, etc. In a
1551 document, tags reference chapters, sections, appendices, etc. Each
1552 tag specifies the name of the file where the corresponding subunit is
1553 defined, and the position of the subunit's definition in that file.
1555 A @dfn{tags table} records the tags extracted by scanning the source
1556 code of a certain program or a certain document. Tags extracted from
1557 generated files reference the original files, rather than the
1558 generated files that were scanned during tag extraction. Examples of
1559 generated files include C files generated from Cweb source files, from
1560 a Yacc parser, or from Lex scanner definitions; @file{.i} preprocessed
1561 C files; and Fortran files produced by preprocessing @file{.fpp}
1564 To produce a tags table, you use the @samp{etags} command,
1565 submitting it a document or the source code of a program.
1566 @samp{etags} writes the tags to a @dfn{tags table file}, or @dfn{tags
1567 file} in short. The conventional name for a tags file is @file{TAGS}.
1569 Emacs uses the information recorded in tags tables in commands that
1570 search or replace through multiple source files: these commands use
1571 the names of the source files recorded in the tags table to know which
1572 files to search. Other commands, such as @kbd{M-.}, which finds the
1573 definition of a function, use the recorded information about the
1574 function names and positions to find the source file and the position
1575 within that file where the function is defined.
1577 @cindex C++ class browser, tags
1579 @cindex class browser, C++
1581 See also the Ebrowse facility, which is tailored for C++.
1582 @xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}.
1585 * Tag Syntax:: Tag syntax for various types of code and text files.
1586 * Create Tags Table:: Creating a tags table with @code{etags}.
1587 * Etags Regexps:: Create arbitrary tags using regular expressions.
1588 * Select Tags Table:: How to visit a tags table.
1589 * Find Tag:: Commands to find the definition of a specific tag.
1590 * Tags Search:: Using a tags table for searching and replacing.
1591 * List Tags:: Listing and finding tags defined in a file.
1595 @subsection Source File Tag Syntax
1597 Here is how tag syntax is defined for the most popular languages:
1601 In C code, any C function or typedef is a tag, and so are definitions of
1602 @code{struct}, @code{union} and @code{enum}.
1603 @code{#define} macro definitions, @code{#undef} and @code{enum}
1605 tags, unless you specify @samp{--no-defines} when making the tags table.
1606 Similarly, global variables are tags, unless you specify
1607 @samp{--no-globals}, and so are struct members, unless you specify
1608 @samp{--no-members}. Use of @samp{--no-globals}, @samp{--no-defines}
1609 and @samp{--no-members} can make the tags table file much smaller.
1611 You can tag function declarations and external variables in addition
1612 to function definitions by giving the @samp{--declarations} option to
1616 In C++ code, in addition to all the tag constructs of C code, member
1617 functions are also recognized; member variables are also recognized,
1618 unless you use the @samp{--no-members} option. Tags for variables and
1619 functions in classes are named @samp{@var{class}::@var{variable}} and
1620 @samp{@var{class}::@var{function}}. @code{operator} definitions have
1621 tag names like @samp{operator+}.
1624 In Java code, tags include all the constructs recognized in C++, plus
1625 the @code{interface}, @code{extends} and @code{implements} constructs.
1626 Tags for variables and functions in classes are named
1627 @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
1630 In La@TeX{} text, the argument of any of the commands @code{\chapter},
1631 @code{\section}, @code{\subsection}, @code{\subsubsection},
1632 @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite},
1633 @code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry},
1634 @code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand},
1635 @code{\newenvironment} or @code{\renewenvironment} is a tag.@refill
1637 Other commands can make tags as well, if you specify them in the
1638 environment variable @env{TEXTAGS} before invoking @code{etags}. The
1639 value of this environment variable should be a colon-separated list of
1640 command names. For example,
1643 TEXTAGS="mycommand:myothercommand"
1648 specifies (using Bourne shell syntax) that the commands
1649 @samp{\mycommand} and @samp{\myothercommand} also define tags.
1652 In Lisp code, any function defined with @code{defun}, any variable
1653 defined with @code{defvar} or @code{defconst}, and in general the first
1654 argument of any expression that starts with @samp{(def} in column zero is
1658 In Scheme code, tags include anything defined with @code{def} or with a
1659 construct whose name starts with @samp{def}. They also include variables
1660 set with @code{set!} at top level in the file.
1663 Several other languages are also supported:
1668 In Ada code, functions, procedures, packages, tasks and types are
1669 tags. Use the @samp{--packages-only} option to create tags for
1672 In Ada, the same name can be used for different kinds of entity
1673 (e.g.@:, for a procedure and for a function). Also, for things like
1674 packages, procedures and functions, there is the spec (i.e.@: the
1675 interface) and the body (i.e.@: the implementation). To make it
1676 easier to pick the definition you want, Ada tag name have suffixes
1677 indicating the type of entity:
1694 Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
1695 directly to the body of the package @code{bidule}, while @kbd{M-x
1696 find-tag @key{RET} bidule @key{RET}} will just search for any tag
1700 In assembler code, labels appearing at the beginning of a line,
1701 followed by a colon, are tags.
1704 In Bison or Yacc input files, each rule defines as a tag the nonterminal
1705 it constructs. The portions of the file that contain C code are parsed
1709 In Cobol code, tags are paragraph names; that is, any word starting in
1710 column 8 and followed by a period.
1713 In Erlang code, the tags are the functions, records and macros defined
1717 In Fortran code, functions, subroutines and block data are tags.
1720 In HTML input files, the tags are the @code{title} and the @code{h1},
1721 @code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchors
1722 and all occurrences of @code{id=}.
1725 In Lua input files, all functions are tags.
1728 In makefiles, targets are tags; additionally, variables are tags
1729 unless you specify @samp{--no-globals}.
1732 In Objective C code, tags include Objective C definitions for classes,
1733 class categories, methods and protocols. Tags for variables and
1734 functions in classes are named @samp{@var{class}::@var{variable}} and
1735 @samp{@var{class}::@var{function}}.
1738 In Pascal code, the tags are the functions and procedures defined in
1742 In Perl code, the tags are the packages, subroutines and variables
1743 defined by the @code{package}, @code{sub}, @code{my} and @code{local}
1744 keywords. Use @samp{--globals} if you want to tag global variables.
1745 Tags for subroutines are named @samp{@var{package}::@var{sub}}. The
1746 name for subroutines defined in the default package is
1747 @samp{main::@var{sub}}.
1750 In PHP code, tags are functions, classes and defines. Vars are tags
1751 too, unless you use the @samp{--no-members} option.
1754 In PostScript code, the tags are the functions.
1757 In Prolog code, tags are predicates and rules at the beginning of
1761 In Python code, @code{def} or @code{class} at the beginning of a line
1765 You can also generate tags based on regexp matching (@pxref{Etags
1766 Regexps}) to handle other formats and languages.
1768 @node Create Tags Table
1769 @subsection Creating Tags Tables
1770 @cindex @code{etags} program
1772 The @code{etags} program is used to create a tags table file. It knows
1773 the syntax of several languages, as described in
1775 the previous section.
1780 Here is how to run @code{etags}:
1783 etags @var{inputfiles}@dots{}
1787 The @code{etags} program reads the specified files, and writes a tags
1788 table named @file{TAGS} in the current working directory. You can
1789 optionally specify a different file name for the tags table by using the
1790 @samp{--output=@var{file}} option; specifying @file{-} as a file name
1791 prints the tags table to standard output.
1793 If the specified files don't exist, @code{etags} looks for
1794 compressed versions of them and uncompresses them to read them. Under
1795 MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz}
1796 if it is given @samp{mycode.c} on the command line and @file{mycode.c}
1799 @code{etags} recognizes the language used in an input file based on
1800 its file name and contents. You can specify the language with the
1801 @samp{--language=@var{name}} option, described below.
1803 If the tags table data become outdated due to changes in the files
1804 described in the table, the way to update the tags table is the same
1805 way it was made in the first place. If the tags table fails to record
1806 a tag, or records it for the wrong file, then Emacs cannot possibly
1807 find its definition until you update the tags table. However, if the
1808 position recorded in the tags table becomes a little bit wrong (due to
1809 other editing), the worst consequence is a slight delay in finding the
1810 tag. Even if the stored position is very far wrong, Emacs will still
1811 find the tag, after searching most of the file for it. That delay is
1812 hardly noticeable with today's computers.
1814 Thus, there is no need to update the tags table after each edit.
1815 You should update a tags table when you define new tags that you want
1816 to have listed, or when you move tag definitions from one file to
1817 another, or when changes become substantial.
1819 One tags table can virtually include another. Specify the included
1820 tags file name with the @samp{--include=@var{file}} option when
1821 creating the file that is to include it. The latter file then acts as
1822 if it covered all the source files specified in the included file, as
1823 well as the files it directly contains.
1825 If you specify the source files with relative file names when you run
1826 @code{etags}, the tags file will contain file names relative to the
1827 directory where the tags file was initially written. This way, you can
1828 move an entire directory tree containing both the tags file and the
1829 source files, and the tags file will still refer correctly to the source
1830 files. If the tags file is @file{-} or is in the @file{/dev} directory,
1831 however, the file names are
1832 made relative to the current working directory. This is useful, for
1833 example, when writing the tags to @file{/dev/stdout}.
1835 When using a relative file name, it should not be a symbolic link
1836 pointing to a tags file in a different directory, because this would
1837 generally render the file names invalid.
1839 If you specify absolute file names as arguments to @code{etags}, then
1840 the tags file will contain absolute file names. This way, the tags file
1841 will still refer to the same files even if you move it, as long as the
1842 source files remain in the same place. Absolute file names start with
1843 @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
1845 When you want to make a tags table from a great number of files, you
1846 may have problems listing them on the command line, because some systems
1847 have a limit on its length. The simplest way to circumvent this limit
1848 is to tell @code{etags} to read the file names from its standard input,
1849 by typing a dash in place of the file names, like this:
1852 find . -name "*.[chCH]" -print | etags -
1855 Use the option @samp{--language=@var{name}} to specify the language
1856 explicitly. You can intermix these options with file names; each one
1857 applies to the file names that follow it. Specify
1858 @samp{--language=auto} to tell @code{etags} to resume guessing the
1859 language from the file names and file contents. Specify
1860 @samp{--language=none} to turn off language-specific processing
1861 entirely; then @code{etags} recognizes tags by regexp matching alone
1862 (@pxref{Etags Regexps}).
1864 The option @samp{--parse-stdin=@var{file}} is mostly useful when
1865 calling @code{etags} from programs. It can be used (only once) in
1866 place of a file name on the command line. @code{Etags} will read from
1867 standard input and mark the produced tags as belonging to the file
1870 @samp{etags --help} outputs the list of the languages @code{etags}
1871 knows, and the file name rules for guessing the language. It also prints
1872 a list of all the available @code{etags} options, together with a short
1873 explanation. If followed by one or more @samp{--language=@var{lang}}
1874 options, it outputs detailed information about how tags are generated for
1878 @subsection Etags Regexps
1880 The @samp{--regex} option provides a general way of recognizing tags
1881 based on regexp matching. You can freely intermix this option with
1882 file names, and each one applies to the source files that follow it.
1883 If you specify multiple @samp{--regex} options, all of them are used
1884 in parallel. The syntax is:
1887 --regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers}
1890 The essential part of the option value is @var{tagregexp}, the
1891 regexp for matching tags. It is always used anchored, that is, it
1892 only matches at the beginning of a line. If you want to allow
1893 indented tags, use a regexp that matches initial whitespace; start it
1896 In these regular expressions, @samp{\} quotes the next character, and
1897 all the GCC character escape sequences are supported (@samp{\a} for
1898 bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for
1899 escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for
1900 carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab).
1902 Ideally, @var{tagregexp} should not match more characters than are
1903 needed to recognize what you want to tag. If the syntax requires you
1904 to write @var{tagregexp} so it matches more characters beyond the tag
1905 itself, you should add a @var{nameregexp}, to pick out just the tag.
1906 This will enable Emacs to find tags more accurately and to do
1907 completion on tag names more reliably. You can find some examples
1910 The @var{modifiers} are a sequence of zero or more characters that
1911 modify the way @code{etags} does the matching. A regexp with no
1912 modifiers is applied sequentially to each line of the input file, in a
1913 case-sensitive way. The modifiers and their meanings are:
1917 Ignore case when matching this regexp.
1919 Match this regular expression against the whole file, so that
1920 multi-line matches are possible.
1922 Match this regular expression against the whole file, and allow
1923 @samp{.} in @var{tagregexp} to match newlines.
1926 The @samp{-R} option cancels all the regexps defined by preceding
1927 @samp{--regex} options. It too applies to the file names following
1928 it. Here's an example:
1931 etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
1932 bar.ber -R --lang=lisp los.er
1936 Here @code{etags} chooses the parsing language for @file{voo.doo} and
1937 @file{bar.ber} according to their contents. @code{etags} also uses
1938 @var{reg1} to recognize additional tags in @file{voo.doo}, and both
1939 @var{reg1} and @var{reg2} to recognize additional tags in
1940 @file{bar.ber}. @var{reg1} is checked against each line of
1941 @file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while
1942 @var{reg2} is checked against the whole @file{bar.ber} file,
1943 permitting multi-line matches, in a case-sensitive way. @code{etags}
1944 uses only the Lisp tags rules, with no user-specified regexp matching,
1945 to recognize tags in @file{los.er}.
1947 You can restrict a @samp{--regex} option to match only files of a
1948 given language by using the optional prefix @var{@{language@}}.
1949 (@samp{etags --help} prints the list of languages recognized by
1950 @code{etags}.) This is particularly useful when storing many
1951 predefined regular expressions for @code{etags} in a file. The
1952 following example tags the @code{DEFVAR} macros in the Emacs source
1953 files, for the C language only:
1956 --regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
1960 When you have complex regular expressions, you can store the list of
1961 them in a file. The following option syntax instructs @code{etags} to
1962 read two files of regular expressions. The regular expressions
1963 contained in the second file are matched without regard to case.
1966 --regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file}
1970 A regex file for @code{etags} contains one regular expression per
1971 line. Empty lines, and lines beginning with space or tab are ignored.
1972 When the first character in a line is @samp{@@}, @code{etags} assumes
1973 that the rest of the line is the name of another file of regular
1974 expressions; thus, one such file can include another file. All the
1975 other lines are taken to be regular expressions. If the first
1976 non-whitespace text on the line is @samp{--}, that line is a comment.
1978 For example, we can create a file called @samp{emacs.tags} with the
1982 -- This is for GNU Emacs C source files
1983 @{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
1987 and then use it like this:
1990 etags --regex=@@emacs.tags *.[ch] */*.[ch]
1993 Here are some more examples. The regexps are quoted to protect them
1994 from shell interpretation.
2002 etags --language=none \
2003 --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
2004 --regex='/###key \(.*\)/\1/' \
2005 --regex='/[ \t]*global[ \t].*/' \
2010 Note that tags are not generated for scripts, so that you have to add
2011 a line by yourself of the form @samp{###key @var{scriptname}} if you
2018 etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
2025 etags --language=none \
2026 --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
2027 --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
2028 \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
2032 @node Select Tags Table
2033 @subsection Selecting a Tags Table
2035 @vindex tags-file-name
2036 @findex visit-tags-table
2037 Emacs has at any time one @dfn{selected} tags table, and all the
2038 commands for working with tags tables use the selected one. To select
2039 a tags table, type @kbd{M-x visit-tags-table}, which reads the tags
2040 table file name as an argument, with @file{TAGS} in the default
2041 directory as the default.
2043 Emacs does not actually read in the tags table contents until you
2044 try to use them; all @code{visit-tags-table} does is store the file
2045 name in the variable @code{tags-file-name}, and setting the variable
2046 yourself is just as good. The variable's initial value is @code{nil};
2047 that value tells all the commands for working with tags tables that
2048 they must ask for a tags table file name to use.
2050 Using @code{visit-tags-table} when a tags table is already loaded
2051 gives you a choice: you can add the new tags table to the current list
2052 of tags tables, or start a new list. The tags commands use all the tags
2053 tables in the current list. If you start a new list, the new tags table
2054 is used @emph{instead} of others. If you add the new table to the
2055 current list, it is used @emph{as well as} the others.
2057 @vindex tags-table-list
2058 You can specify a precise list of tags tables by setting the variable
2059 @code{tags-table-list} to a list of strings, like this:
2061 @c keep this on two lines for formatting in smallbook
2064 (setq tags-table-list
2065 '("~/emacs" "/usr/local/lib/emacs/src"))
2070 This tells the tags commands to look at the @file{TAGS} files in your
2071 @file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
2072 directory. The order depends on which file you are in and which tags
2073 table mentions that file, as explained above.
2075 Do not set both @code{tags-file-name} and @code{tags-table-list}.
2078 @subsection Finding a Tag
2080 The most important thing that a tags table enables you to do is to find
2081 the definition of a specific tag.
2084 @item M-.@: @var{tag} @key{RET}
2085 Find first definition of @var{tag} (@code{find-tag}).
2087 Find next alternate definition of last tag specified.
2089 Go back to previous tag found.
2090 @item C-M-. @var{pattern} @key{RET}
2091 Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
2093 Find the next tag whose name matches the last pattern used.
2094 @item C-x 4 .@: @var{tag} @key{RET}
2095 Find first definition of @var{tag}, but display it in another window
2096 (@code{find-tag-other-window}).
2097 @item C-x 5 .@: @var{tag} @key{RET}
2098 Find first definition of @var{tag}, and create a new frame to select the
2099 buffer (@code{find-tag-other-frame}).
2101 Pop back to where you previously invoked @kbd{M-.} and friends.
2106 @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
2107 a specified tag. It searches through the tags table for that tag, as a
2108 string, and then uses the tags table info to determine the file that the
2109 definition is in and the approximate character position in the file of
2110 the definition. Then @code{find-tag} visits that file, moves point to
2111 the approximate character position, and searches ever-increasing
2112 distances away to find the tag definition.
2114 If an empty argument is given (just type @key{RET}), the balanced
2115 expression in the buffer before or around point is used as the
2116 @var{tag} argument. @xref{Expressions}.
2118 You don't need to give @kbd{M-.} the full name of the tag; a part
2119 will do. This is because @kbd{M-.} finds tags in the table which
2120 contain @var{tag} as a substring. However, it prefers an exact match
2121 to a substring match. To find other tags that match the same
2122 substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
2123 M-.}; this does not read a tag name, but continues searching the tags
2124 table's text for another tag containing the same substring last used.
2125 If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier
2126 alternative to @kbd{C-u M-.}.
2129 @findex find-tag-other-window
2131 @findex find-tag-other-frame
2132 Like most commands that can switch buffers, @code{find-tag} has a
2133 variant that displays the new buffer in another window, and one that
2134 makes a new frame for it. The former is @w{@kbd{C-x 4 .}}, which invokes
2135 the command @code{find-tag-other-window}. The latter is @w{@kbd{C-x 5 .}},
2136 which invokes @code{find-tag-other-frame}.
2138 To move back to places you've found tags recently, use @kbd{C-u -
2139 M-.}; more generally, @kbd{M-.} with a negative numeric argument. This
2140 command can take you to another buffer. @w{@kbd{C-x 4 .}} with a negative
2141 argument finds the previous tag location in another window.
2144 @findex pop-tag-mark
2145 @vindex find-tag-marker-ring-length
2146 As well as going back to places you've found tags recently, you can go
2147 back to places @emph{from where} you found them. Use @kbd{M-*}, which
2148 invokes the command @code{pop-tag-mark}, for this. Typically you would
2149 find and study the definition of something with @kbd{M-.} and then
2150 return to where you were with @kbd{M-*}.
2152 Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
2153 a depth determined by the variable @code{find-tag-marker-ring-length}.
2155 @findex find-tag-regexp
2157 The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
2158 match a specified regular expression. It is just like @kbd{M-.} except
2159 that it does regexp matching instead of substring matching.
2162 @subsection Searching and Replacing with Tags Tables
2163 @cindex search and replace in multiple files
2164 @cindex multiple-file search and replace
2166 The commands in this section visit and search all the files listed
2167 in the selected tags table, one by one. For these commands, the tags
2168 table serves only to specify a sequence of files to search. These
2169 commands scan the list of tags tables starting with the first tags
2170 table (if any) that describes the current file, proceed from there to
2171 the end of the list, and then scan from the beginning of the list
2172 until they have covered all the tables in the list.
2175 @item M-x tags-search @key{RET} @var{regexp} @key{RET}
2176 Search for @var{regexp} through the files in the selected tags
2178 @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
2179 Perform a @code{query-replace-regexp} on each file in the selected tags table.
2181 Restart one of the commands above, from the current location of point
2182 (@code{tags-loop-continue}).
2186 @kbd{M-x tags-search} reads a regexp using the minibuffer, then
2187 searches for matches in all the files in the selected tags table, one
2188 file at a time. It displays the name of the file being searched so you
2189 can follow its progress. As soon as it finds an occurrence,
2190 @code{tags-search} returns.
2193 @findex tags-loop-continue
2194 Having found one match, you probably want to find all the rest. To find
2195 one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
2196 @code{tags-search}. This searches the rest of the current buffer, followed
2197 by the remaining files of the tags table.@refill
2199 @findex tags-query-replace
2200 @kbd{M-x tags-query-replace} performs a single
2201 @code{query-replace-regexp} through all the files in the tags table. It
2202 reads a regexp to search for and a string to replace with, just like
2203 ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
2204 tags-search}, but repeatedly, processing matches according to your
2205 input. @xref{Replace}, for more information on query replace.
2207 @vindex tags-case-fold-search
2208 @cindex case-sensitivity and tags search
2209 You can control the case-sensitivity of tags search commands by
2210 customizing the value of the variable @code{tags-case-fold-search}. The
2211 default is to use the same setting as the value of
2212 @code{case-fold-search} (@pxref{Search Case}).
2214 It is possible to get through all the files in the tags table with a
2215 single invocation of @kbd{M-x tags-query-replace}. But often it is
2216 useful to exit temporarily, which you can do with any input event that
2217 has no special query replace meaning. You can resume the query
2218 replace subsequently by typing @kbd{M-,}; this command resumes the
2219 last tags search or replace command that you did. For instance, to
2220 skip the rest of the current file, you can type @kbd{M-> M-,}.
2222 The commands in this section carry out much broader searches than the
2223 @code{find-tag} family. The @code{find-tag} commands search only for
2224 definitions of tags that match your substring or regexp. The commands
2225 @code{tags-search} and @code{tags-query-replace} find every occurrence
2226 of the regexp, as ordinary search commands and replace commands do in
2229 These commands create buffers only temporarily for the files that they
2230 have to search (those which are not already visited in Emacs buffers).
2231 Buffers in which no match is found are quickly killed; the others
2234 It may have struck you that @code{tags-search} is a lot like
2235 @code{grep}. You can also run @code{grep} itself as an inferior of
2236 Emacs and have Emacs show you the matching lines one by one.
2237 @xref{Grep Searching}.
2240 @subsection Tags Table Inquiries
2243 @item M-x list-tags @key{RET} @var{file} @key{RET}
2244 Display a list of the tags defined in the program file @var{file}.
2245 @item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
2246 Display a list of all tags matching @var{regexp}.
2250 @kbd{M-x list-tags} reads the name of one of the files described by
2251 the selected tags table, and displays a list of all the tags defined in
2252 that file. The ``file name'' argument is really just a string to
2253 compare against the file names recorded in the tags table; it is read as
2254 a string rather than as a file name. Therefore, completion and
2255 defaulting are not available, and you must enter the file name the same
2256 way it appears in the tags table. Do not include a directory as part of
2257 the file name unless the file name recorded in the tags table includes a
2260 @findex tags-apropos
2261 @vindex tags-apropos-verbose
2262 @kbd{M-x tags-apropos} is like @code{apropos} for tags
2263 (@pxref{Apropos}). It finds all the tags in the selected tags table
2264 whose entries match @var{regexp}, and displays them. If the variable
2265 @code{tags-apropos-verbose} is non-@code{nil}, it displays the names
2266 of the tags files together with the tag names.
2268 @vindex tags-tag-face
2269 @vindex tags-apropos-additional-actions
2270 You can customize the appearance of the output by setting the
2271 variable @code{tags-tag-face} to a face. You can display additional
2272 output with @kbd{M-x tags-apropos} by customizing the variable
2273 @code{tags-apropos-additional-actions}---see its documentation for
2276 You can also use the collection of tag names to complete a symbol
2277 name in the buffer. @xref{Symbol Completion}.
2280 @include emerge-xtra.texi
2284 @section Emacs Development Environment
2285 @cindex EDE (Emacs Development Environment)
2286 @cindex Emacs Development Environment
2287 @cindex Integrated development environment
2289 EDE (@dfn{Emacs Development Environment}) is a package that simplifies
2290 the task of creating, building, and debugging large programs with
2291 Emacs. It provides some of the features of an IDE, or @dfn{Integrated
2292 Development Environment}, in Emacs.
2294 This section provides a brief description of EDE usage.
2296 For full details, see @ref{Top, EDE,, ede, Emacs Development Environment}.
2299 For full details on Ede, type @kbd{C-h i} and then select the EDE
2303 EDE is implemented as a global minor mode (@pxref{Minor Modes}). To
2304 enable it, type @kbd{M-x global-ede-mode} or click on the
2305 @samp{Project Support (EDE)} item in the @samp{Tools} menu. You can
2306 also enable EDE each time you start Emacs, by adding the following
2307 line to your initialization file:
2314 Activating EDE adds a menu named @samp{Development} to the menu bar.
2315 Many EDE commands, including the ones described below, can be invoked
2318 EDE organizes files into @dfn{projects}, which correspond to
2319 directory trees. The @dfn{project root} is the topmost directory of a
2320 project. To define a new project, visit a file in the desired project
2321 root and type @kbd{M-x ede-new}. This command prompts for a
2322 @dfn{project type}, which refers to the underlying method that EDE
2323 will use to manage the project (@pxref{Creating a Project, EDE,, ede,
2324 Emacs Development Environment}). The most common project types are
2325 @samp{Make}, which uses Makefiles, and @samp{Automake}, which uses GNU
2326 Automake (@pxref{Top, Automake,, automake, Automake}). In both cases,
2327 EDE also creates a file named @file{Project.ede}, which stores
2328 information about the project.
2330 A project may contain one or more @dfn{targets}. A target can be an
2331 object file, executable program, or some other type of file, which is
2332 ``built'' from one or more of the files in the project.
2334 To add a new @dfn{target} to a project, type @kbd{C-c . t}
2335 (@code{M-x ede-new-target}). This command also asks if you wish to
2336 ``add'' the current file to that target, which means that the target
2337 is to be built from that file. After you have defined a target, you
2338 can add more files to it by typing @kbd{C-c . a}
2339 (@code{ede-add-file}).
2341 To build a target, type @kbd{C-c . c} (@code{ede-compile-target}).
2342 To build all the targets in the project, type @kbd{C-c . C}
2343 (@code{ede-compile-project}). EDE uses the file types to guess how
2344 the target should be built.
2347 arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb