1 @c This is part of the Emacs manual., Abbrevs, This is part of the Emacs manual., Top
2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2014 Free Software
4 @c See file emacs.texi for copying conditions.
6 @chapter Maintaining Large Programs
8 This chapter describes Emacs features for maintaining large
9 programs. If you are maintaining a large Lisp program, then in
10 addition to the features described here, you may find
11 the @file{ERT} (``Emacs Lisp Regression Testing'') library useful
12 (@pxref{Top,,ERT,ert, Emacs Lisp Regression Testing}).
15 * Version Control:: Using version control systems.
16 * Change Log:: Maintaining a change history for your program.
17 * Tags:: Go directly to any function in your program in one
18 command. Tags remembers which file it is in.
19 * EDE:: An integrated development environment for Emacs.
21 * Emerge:: A convenient way of merging two versions of a program.
26 @section Version Control
27 @cindex version control
29 A @dfn{version control system} is a program that can record multiple
30 versions of a source file, storing information such as the creation
31 time of each version, who made it, and a description of what was
34 The Emacs version control interface is called @dfn{VC}@. VC
35 commands work with several different version control systems;
36 currently, it supports Bazaar, CVS, Git, Mercurial, Monotone, RCS,
37 SCCS/CSSC, and Subversion. Of these, the GNU project distributes CVS,
40 VC is enabled automatically whenever you visit a file governed by a
41 version control system. To disable VC entirely, set the customizable
42 variable @code{vc-handled-backends} to @code{nil}
44 (@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
47 (@pxref{Customizing VC}).
51 * Introduction to VC:: How version control works in general.
52 * VC Mode Line:: How the mode line shows version control status.
53 * Basic VC Editing:: How to edit a file under version control.
54 * Log Buffer:: Features available in log entry buffers.
55 * Registering:: Putting a file under version control.
56 * Old Revisions:: Examining and comparing old versions.
57 * VC Change Log:: Viewing the VC Change Log.
58 * VC Undo:: Canceling changes before or after committing.
59 * VC Ignore:: Ignore files under version control system.
60 * VC Directory Mode:: Listing files managed by version control.
61 * Branches:: Multiple lines of development.
63 * Miscellaneous VC:: Various other commands and features of VC.
64 * Customizing VC:: Variables that change VC's behavior.
68 @node Introduction to VC
69 @subsection Introduction to Version Control
71 VC allows you to use a version control system from within Emacs,
72 integrating the version control operations smoothly with editing. It
73 provides a uniform interface for common operations in many version
76 Some uncommon or intricate version control operations, such as
77 altering repository settings, are not supported in VC@. You should
78 perform such tasks outside Emacs, e.g., via the command line.
80 This section provides a general overview of version control, and
81 describes the version control systems that VC supports. You can skip
82 this section if you are already familiar with the version control system
86 * Why Version Control?:: Understanding the problems it addresses.
87 * Version Control Systems:: Supported version control back-end systems.
88 * VCS Concepts:: Words and concepts related to version control.
89 * VCS Merging:: How file conflicts are handled.
90 * VCS Changesets:: How changes are grouped.
91 * VCS Repositories:: Where version control repositories are stored.
92 * Types of Log File:: The VCS log in contrast to the ChangeLog.
95 @node Why Version Control?
96 @subsubsection Understanding the problems it addresses
98 Version control systems provide you with three important
103 @dfn{Reversibility}: the ability to back up to a previous state if you
104 discover that some modification you did was a mistake or a bad idea.
107 @dfn{Concurrency}: the ability to have many people modifying the same
108 collection of files knowing that conflicting modifications can be
109 detected and resolved.
112 @dfn{History}: the ability to attach historical data to your data,
113 such as explanatory comments about the intention behind each change to
114 it. Even for a programmer working solo, change histories are an
115 important aid to memory; for a multi-person project, they are a
116 vitally important form of communication among developers.
119 @node Version Control Systems
120 @subsubsection Supported Version Control Systems
122 @cindex back end (version control)
123 VC currently works with many different version control systems,
124 which it refers to as @dfn{back ends}:
130 SCCS was the first version control system ever built, and was long ago
131 superseded by more advanced ones. VC compensates for certain features
132 missing in SCCS (e.g., tag names for releases) by implementing them
133 itself. Other VC features, such as multiple branches, are simply
134 unavailable. Since SCCS is non-free, we recommend avoiding it.
138 CSSC is a free replacement for SCCS@. You should use CSSC only if, for
139 some reason, you cannot use a more recent and better-designed version
144 RCS is the free version control system around which VC was initially
145 built. It is relatively primitive: it cannot be used over the
146 network, and works at the level of individual files. Almost
147 everything you can do with RCS can be done through VC.
151 CVS is the free version control system that was, until recently (circa
152 2008), used by the majority of free software projects. Nowadays, it
153 is slowly being superseded by newer systems. CVS allows concurrent
154 multi-user development either locally or over the network. Unlike
155 newer systems, it lacks support for atomic commits and file
156 moving/renaming. VC supports all basic editing operations under CVS.
161 Subversion (svn) is a free version control system designed to be
162 similar to CVS but without its problems (e.g., it supports atomic
163 commits of filesets, and versioning of directories, symbolic links,
164 meta-data, renames, copies, and deletes).
168 Git is a decentralized version control system originally invented by
169 Linus Torvalds to support development of Linux (his kernel). VC
170 supports many common Git operations, but others, such as repository
171 syncing, must be done from the command line.
176 Mercurial (hg) is a decentralized version control system broadly
177 resembling Git. VC supports most Mercurial commands, with the
178 exception of repository sync operations.
183 Bazaar (bzr) is a decentralized version control system that supports
184 both repository-based and decentralized versioning. VC supports most
185 basic editing operations under Bazaar.
190 SRC (src) is RCS, reloaded - a specialized version-control system
191 designed for single-file projects worked on by only one person. It
192 allows multiple files with independent version-control histories to
193 exist in one directory, and is thus particularly well suited for
194 maintaining small documents, scripts, and dotfiles. While it uses RCS
195 for revision storage, it presents a modern user interface featuring
196 lockless operation and integer sequential version numbers. VC
197 supports almost all SRC operations.
201 @subsubsection Concepts of Version Control
204 @cindex registered file
205 When a file is under version control, we say that it is
206 @dfn{registered} in the version control system. The system has a
207 @dfn{repository} which stores both the file's present state and its
208 change history---enough to reconstruct the current version or any
209 earlier version. The repository also contains other information, such
210 as @dfn{log entries} that describe the changes made to each file.
213 @cindex checking out files
214 The copy of a version-controlled file that you actually edit is
215 called the @dfn{work file}. You can change each work file as you
216 would an ordinary file. After you are done with a set of changes, you
217 may @dfn{commit} (or @dfn{check in}) the changes; this records the
218 changes in the repository, along with a descriptive log entry.
221 A directory tree of work files is called a @dfn{working tree}.
225 Each commit creates a new @dfn{revision} in the repository. The
226 version control system keeps track of all past revisions and the
227 changes that were made in each revision. Each revision is named by a
228 @dfn{revision ID}, whose format depends on the version control system;
229 in the simplest case, it is just an integer.
231 To go beyond these basic concepts, you will need to understand three
232 aspects in which version control systems differ. As explained in the
233 next three sections, they can be lock-based or merge-based; file-based
234 or changeset-based; and centralized or decentralized. VC handles all
235 these modes of operation, but it cannot hide the differences.
238 @subsubsection Merge-based vs lock-based Version Control
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 @cindex merging-based version
245 In a version control system that uses merging, each user may modify
246 a work file at any time. The system lets you @dfn{merge} your work
247 file, which may contain changes that have not been committed, with the
248 latest changes that others have committed.
250 @cindex locking-based version
251 Older version control systems use a @dfn{locking} scheme instead.
252 Here, work files are normally read-only. To edit a file, you ask the
253 version control system to make it writable for you by @dfn{locking}
254 it; only one user can lock a given file at any given time. This
255 procedure is analogous to, but different from, the locking that Emacs
256 uses to detect simultaneous editing of ordinary files
257 (@pxref{Interlocking}). When you commit your changes, that unlocks
258 the file, and the work file becomes read-only again. Other users may
259 then lock the file to make their own changes.
261 Both locking and merging systems can have problems when multiple
262 users try to modify the same file at the same time. Locking systems
263 have @dfn{lock conflicts}; a user may try to check a file out and be
264 unable to because it is locked. In merging systems, @dfn{merge
265 conflicts} happen when you commit a change to a file that conflicts
266 with a change committed by someone else after your checkout. Both
267 kinds of conflict have to be resolved by human judgment and
268 communication. Experience has shown that merging is superior to
269 locking, both in convenience to developers and in minimizing the
270 number and severity of conflicts that actually occur.
272 SCCS always uses locking. RCS is lock-based by default but can be
273 told to operate in a merging style. CVS and Subversion are
274 merge-based by default but can be told to operate in a locking mode.
275 Decentralized version control systems, such as Git and Mercurial, are
276 exclusively merging-based.
278 VC mode supports both locking and merging version control. The
279 terms ``commit'' and ``update'' are used in newer version control
280 systems; older lock-based systems use the terms ``check in'' and
281 ``check out''. VC hides the differences between them as much as
285 @subsubsection Changeset-based vs File-based Version Control
287 @cindex file-based version control
288 On SCCS, RCS, CVS, and other early version control systems, version
289 control operations are @dfn{file-based}: each file has its own comment
290 and revision history separate from that of all other files. Newer
291 systems, beginning with Subversion, are @dfn{changeset-based}: a
292 commit may include changes to several files, and the entire set of
293 changes is handled as a unit. Any comment associated with the change
294 does not belong to a single file, but to the changeset itself.
296 @cindex changeset-based version control
297 Changeset-based version control is more flexible and powerful than
298 file-based version control; usually, when a change to multiple files
299 has to be reversed, it's good to be able to easily identify and remove
302 @node VCS Repositories
303 @subsubsection Decentralized vs Centralized Repositories
305 @cindex centralized version control
306 @cindex decentralized version control
307 @cindex distributed version control
308 Early version control systems were designed around a
309 @dfn{centralized} model in which each project has only one repository
310 used by all developers. SCCS, RCS, CVS, and Subversion share this
311 kind of model. One of its drawbacks is that the repository is a choke
312 point for reliability and efficiency.
314 GNU Arch pioneered the concept of @dfn{distributed} or
315 @dfn{decentralized} version control, later implemented in Git,
316 Mercurial, and Bazaar. A project may have several different
317 repositories, and these systems support a sort of super-merge between
318 repositories that tries to reconcile their change histories. In
319 effect, there is one repository for each developer, and repository
320 merges take the place of commit operations.
322 VC helps you manage the traffic between your personal workfiles and
323 a repository. Whether the repository is a single master, or one of a
324 network of peer repositories, is not something VC has to care about.
326 @node Types of Log File
327 @subsubsection Types of Log File
328 @cindex types of log file
329 @cindex log File, types of
330 @cindex version control log
332 Projects that use a version control system can have two types of log
333 for changes. One is the log maintained by the version control system:
334 each time you commit a change, you fill out a @dfn{log entry} for the
335 change (@pxref{Log Buffer}). This is called the @dfn{version control
338 The other kind of log is the file @file{ChangeLog} (@pxref{Change
339 Log}). It provides a chronological record of all changes to a large
340 portion of a program---typically one directory and its subdirectories.
341 A small program would use one @file{ChangeLog} file; a large program
342 may have a @file{ChangeLog} file in each major directory.
343 @xref{Change Log}. Programmers have used change logs since long
344 before version control systems.
346 Changeset-based version systems typically maintain a changeset-based
347 modification log for the entire system, which makes change log files
348 somewhat redundant. One advantage that they retain is that it is
349 sometimes useful to be able to view the transaction history of a
350 single directory separately from those of other directories. Another
351 advantage is that commit logs can't be fixed in many version control
354 A project maintained with version control can use just the version
355 control log, or it can use both kinds of logs. It can handle some
356 files one way and some files the other way. Each project has its
357 policy, which you should follow.
359 When the policy is to use both, you typically want to write an entry
360 for each change just once, then put it into both logs. You can write
361 the entry in @file{ChangeLog}, then copy it to the log buffer with
362 @kbd{C-c C-a} when committing the change (@pxref{Log Buffer}). Or you
363 can write the entry in the log buffer while committing the change, and
364 later use the @kbd{C-x v a} command to copy it to @file{ChangeLog}
366 (@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
369 (@pxref{Change Logs and VC}).
373 @subsection Version Control and the Mode Line
374 @cindex VC mode line indicator
376 When you visit a file that is under version control, Emacs indicates
377 this on the mode line. For example, @samp{Bzr-1223} says that Bazaar
378 is used for that file, and the current revision ID is 1223.
380 @cindex version control status
381 The character between the back-end name and the revision ID
382 indicates the @dfn{version control status} of the work file. In a
383 merge-based version control system, a @samp{-} character indicates
384 that the work file is unmodified, and @samp{:} indicates that it has
385 been modified. @samp{!} indicates that the file contains conflicts as
386 result of a recent merge operation (@pxref{Merging}), or that the file
387 was removed from the version control. Finally, @samp{?} means that
388 the file is under version control, but is missing from the working
391 In a lock-based system, @samp{-} indicates an unlocked file, and
392 @samp{:} a locked file; if the file is locked by another user (for
393 instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
394 @samp{@@} means that the file was locally added, but not yet committed
395 to the master repository.
397 On a graphical display, you can move the mouse over this mode line
398 indicator to pop up a ``tool-tip'', which displays a more verbose
399 description of the version control status. Pressing @kbd{Mouse-1}
400 over the indicator pops up a menu of VC commands, identical to
401 @samp{Tools / Version Control} on the menu bar.
403 @vindex auto-revert-check-vc-info
404 When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is
405 under version control, it updates the version control information in
406 the mode line. However, Auto Revert mode may not properly update this
407 information if the version control status changes without changes to
408 the work file, from outside the current Emacs session. If you set
409 @code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates
410 the version control status information every
411 @code{auto-revert-interval} seconds, even if the work file itself is
412 unchanged. The resulting CPU usage depends on the version control
413 system, but is usually not excessive.
415 @node Basic VC Editing
416 @subsection Basic Editing under Version Control
420 Most VC commands operate on @dfn{VC filesets}. A VC fileset is a
421 collection of one or more files that a VC operation acts on. When you
422 type VC commands in a buffer visiting a version-controlled file, the
423 VC fileset is simply that one file. When you type them in a VC
424 Directory buffer, and some files in it are marked, the VC fileset
425 consists of the marked files (@pxref{VC Directory Mode}).
427 On modern changeset-based version control systems (@pxref{VCS
428 Changesets}), VC commands handle multi-file VC filesets as a group.
429 For example, committing a multi-file VC fileset generates a single
430 revision, containing the changes to all those files. On older
431 file-based version control systems like CVS, each file in a multi-file
432 VC fileset is handled individually; for example, a commit generates
433 one revision for each changed file.
437 Perform the next appropriate version control operation on the current
441 @findex vc-next-action
443 The principal VC command is a multi-purpose command, @kbd{C-x v v}
444 (@code{vc-next-action}), which performs the ``most appropriate''
445 action on the current VC fileset: either registering it with a version
446 control system, or committing it, or unlocking it, or merging changes
447 into it. The precise actions are described in detail in the following
448 subsections. You can use @kbd{C-x v v} either in a file-visiting
449 buffer or in a VC Directory buffer.
451 Note that VC filesets are distinct from the ``named filesets'' used
452 for viewing and visiting files in functional groups
453 (@pxref{Filesets}). Unlike named filesets, VC filesets are not named
454 and don't persist across sessions.
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.
462 @node VC With A Merging VCS
463 @subsubsection Basic Version Control with Merging
465 On a merging-based version control system (i.e., most modern ones;
466 @pxref{VCS Merging}), @kbd{C-x v v} does the following:
470 If there is more than one file in the VC fileset and the files have
471 inconsistent version control statuses, signal an error. (Note,
472 however, that a fileset is allowed to include both ``newly-added''
473 files and ``modified'' files; @pxref{Registering}.)
476 If none of the files in the VC fileset are registered with a version
477 control system, register the VC fileset, i.e., place it under version
478 control. @xref{Registering}. If Emacs cannot find a system to
479 register under, it prompts for a repository type, creates a new
480 repository, and registers the VC fileset with it.
483 If every work file in the VC fileset is unchanged, do nothing.
486 If every work file in the VC fileset has been modified, commit the
487 changes. To do this, Emacs pops up a @file{*vc-log*} buffer; type the
488 desired log entry for the new revision, followed by @kbd{C-c C-c} to
489 commit. @xref{Log Buffer}.
491 If committing to a shared repository, the commit may fail if the
492 repository that has been changed since your last update. In that
493 case, you must perform an update before trying again. On a
494 decentralized version control system, use @kbd{C-x v +} (@pxref{VC
495 Pull}) or @kbd{C-x v m} (@pxref{Merging}). On a centralized version
496 control system, type @kbd{C-x v v} again to merge in the repository
500 Finally, if you are using a centralized version control system, check
501 if each work file in the VC fileset is up-to-date. If any file has
502 been changed in the repository, offer to update it.
505 These rules also apply when you use RCS in its ``non-locking'' mode,
506 except that changes are not automatically merged from the repository.
507 Nothing informs you if another user has committed changes in the same
508 file since you began editing it; when you commit your revision, his
509 changes are removed (however, they remain in the repository and are
510 thus not irrevocably lost). Therefore, you must verify that the
511 current revision is unchanged before committing your changes. In
512 addition, locking is possible with RCS even in this mode: @kbd{C-x v
513 v} with an unmodified file locks the file, just as it does with RCS in
514 its normal locking mode (@pxref{VC With A Locking VCS}).
516 @node VC With A Locking VCS
517 @subsubsection Basic Version Control with Locking
519 On a locking-based version control system (such as SCCS, and RCS in
520 its default mode), @kbd{C-x v v} does the following:
524 If there is more than one file in the VC fileset and the files have
525 inconsistent version control statuses, signal an error.
528 If each file in the VC fileset is not registered with a version
529 control system, register the VC fileset. @xref{Registering}. If
530 Emacs cannot find a system to register under, it prompts for a
531 repository type, creates a new repository, and registers the VC
535 If each file is registered and unlocked, lock it and make it writable,
536 so that you can begin to edit it.
539 If each file is locked by you and contains changes, commit the
540 changes. To do this, Emacs pops up a @file{*vc-log*} buffer; type the
541 desired log entry for the new revision, followed by @kbd{C-c C-c} to
542 commit (@pxref{Log Buffer}).
545 If each file is locked by you, but you have not changed it, release
546 the lock and make the file read-only again.
549 If each file is locked by another user, ask whether you want to
550 ``steal the lock''. If you say yes, the file becomes locked by you,
551 and a warning message is sent to the user who had formerly locked the
555 These rules also apply when you use CVS in locking mode, except
556 that CVS does not support stealing locks.
558 @node Advanced C-x v v
559 @subsubsection Advanced Control in @kbd{C-x v v}
561 @cindex revision ID in version control
562 When you give a prefix argument to @code{vc-next-action} (@kbd{C-u
563 C-x v v}), it still performs the next logical version control
564 operation, but accepts additional arguments to specify precisely how
569 @cindex specific version control system
570 You can specify the name of a version control system. This is useful
571 if the fileset can be managed by more than one version control system,
572 and Emacs fails to detect the correct one.
575 Otherwise, if using CVS or RCS, you can specify a revision ID.
577 If the fileset is modified (or locked), this makes Emacs commit with
578 that revision ID@. You can create a new branch by supplying an
579 appropriate revision ID (@pxref{Branches}).
581 If the fileset is unmodified (and unlocked), this checks the specified
582 revision into the working tree. You can also specify a revision on
583 another branch by giving its revision or branch ID (@pxref{Switching
584 Branches}). An empty argument (i.e., @kbd{C-u C-x v v @key{RET}})
585 checks out the latest (``head'') revision on the current branch.
587 This signals an error on a decentralized version control system.
588 Those systems do not let you specify your own revision IDs, nor do
589 they use the concept of ``checking out'' individual files.
593 @subsection Features of the Log Entry Buffer
595 @cindex C-c C-c @r{(Log Edit mode)}
596 @findex log-edit-done
597 When you tell VC to commit a change, it pops up a buffer named
598 @file{*vc-log*}. In this buffer, you should write a @dfn{log entry}
599 describing the changes you have made (@pxref{Why Version Control?}).
600 After you are done, type @kbd{C-c C-c} (@code{log-edit-done}) to exit
601 the buffer and commit the change, together with your log entry.
603 @cindex Log Edit mode
604 @cindex mode, Log Edit
605 @vindex vc-log-mode-hook
606 @c FIXME: Mention log-edit-mode-hook here? --xfq
607 The major mode for the @file{*vc-log*} buffer is Log Edit mode, a
608 variant of Text mode (@pxref{Text Mode}). On entering Log Edit mode,
609 Emacs runs the hooks @code{text-mode-hook} and @code{vc-log-mode-hook}
612 In the @file{*vc-log*} buffer, you can write one or more @dfn{header
613 lines}, specifying additional information to be supplied to the
614 version control system. Each header line must occupy a single line at
615 the top of the buffer; the first line that is not a header line is
616 treated as the start of the log entry. For example, the following
617 header line states that the present change was not written by you, but
618 by another developer:
621 Author: J. R. Hacker <jrh@@example.com>
625 Apart from the @samp{Author} header, Emacs recognizes the headers
626 @samp{Date} (a manually-specified commit time) and @samp{Fixes} (a
627 reference to a bug fixed by the change). Not all version control
628 systems recognize all headers: Bazaar recognizes all three headers,
629 while Git, Mercurial, and Monotone recognize only @samp{Author} and
630 @samp{Date}. If you specify a header for a system that does not
631 support it, the header is treated as part of the log entry.
633 @kindex C-c C-f @r{(Log Edit mode)}
634 @findex log-edit-show-files
635 @kindex C-c C-d @r{(Log Edit mode)}
636 @findex log-edit-show-diff
637 While in the @file{*vc-log*} buffer, the ``current VC fileset'' is
638 considered to be the fileset that will be committed if you type
639 @w{@kbd{C-c C-c}}. To view a list of the files in the VC fileset,
640 type @w{@kbd{C-c C-f}} (@code{log-edit-show-files}). To view a diff
641 of changes between the VC fileset and the version from which you
642 started editing (@pxref{Old Revisions}), type @kbd{C-c C-d}
643 (@code{log-edit-show-diff}).
645 @kindex C-c C-a @r{(Log Edit mode)}
646 @findex log-edit-insert-changelog
647 If the VC fileset includes one or more @file{ChangeLog} files
648 (@pxref{Change Log}), type @kbd{C-c C-a}
649 (@code{log-edit-insert-changelog}) to pull the relevant entries into
650 the @file{*vc-log*} buffer. If the topmost item in each
651 @file{ChangeLog} was made under your user name on the current date,
652 this command searches that item for entries matching the file(s) to be
653 committed, and inserts them.
655 If you are using CVS or RCS, see @ref{Change Logs and VC}, for the
656 opposite way of working---generating ChangeLog entries from the Log
660 To abort a commit, just @emph{don't} type @kbd{C-c C-c} in that
661 buffer. You can switch buffers and do other editing. As long as you
662 don't try to make another commit, the entry you were editing remains
663 in the @file{*vc-log*} buffer, and you can go back to that buffer at
664 any time to complete the commit.
666 @kindex M-n @r{(Log Edit mode)}
667 @kindex M-p @r{(Log Edit mode)}
668 @kindex M-s @r{(Log Edit mode)}
669 @kindex M-r @r{(Log Edit mode)}
670 You can also browse the history of previous log entries to duplicate
671 a commit comment. This can be useful when you want to make several
672 commits with similar comments. The commands @kbd{M-n}, @kbd{M-p},
673 @kbd{M-s} and @kbd{M-r} for doing this work just like the minibuffer
674 history commands (@pxref{Minibuffer History}), except that they are
675 used outside the minibuffer.
678 @subsection Registering a File for Version Control
682 Register the visited file for version control.
687 The command @kbd{C-x v i} (@code{vc-register}) @dfn{registers} each
688 file in the current VC fileset, placing it under version control.
689 This is essentially equivalent to the action of @kbd{C-x v v} on an
690 unregistered VC fileset (@pxref{Basic VC Editing}), except that if the
691 VC fileset is already registered, @kbd{C-x v i} signals an error
692 whereas @kbd{C-x v v} performs some other action.
694 To register a file, Emacs must choose a version control system. For
695 a multi-file VC fileset, the VC Directory buffer specifies the system
696 to use (@pxref{VC Directory Mode}). For a single-file VC fileset, if
697 the file's directory already contains files registered in a version
698 control system, or if the directory is part of a directory tree
699 controlled by a version control system, Emacs chooses that system. In
700 the event that more than one version control system is applicable,
701 Emacs uses the one that appears first in the variable
703 @code{vc-handled-backends}.
706 @code{vc-handled-backends} (@pxref{Customizing VC}).
708 If Emacs cannot find a version control system to register the file
709 under, it prompts for a repository type, creates a new repository, and
710 registers the file into that repository.
712 On most version control systems, registering a file with @kbd{C-x v
713 i} or @kbd{C-x v v} adds it to the ``working tree'' but not to the
714 repository. Such files are labeled as @samp{added} in the VC
715 Directory buffer, and show a revision ID of @samp{@@@@} in the mode
716 line. To make the registration take effect in the repository, you
717 must perform a commit (@pxref{Basic VC Editing}). Note that a single
718 commit can include both file additions and edits to existing files.
720 On a locking-based version control system (@pxref{VCS Merging}),
721 registering a file leaves it unlocked and read-only. Type @kbd{C-x v
722 v} to start editing it.
725 @subsection Examining And Comparing Old Revisions
729 Compare the work files in the current VC fileset with the versions you
730 started from (@code{vc-diff}). With a prefix argument, prompt for two
731 revisions of the current VC fileset and compare them. You can also
732 call this command from a Dired buffer (@pxref{Dired}).
736 Like @kbd{C-x v =}, but using Ediff. @xref{Top,, Ediff, ediff, The
741 Compare the entire working tree to the revision you started from
742 (@code{vc-root-diff}). With a prefix argument, prompt for two
743 revisions and compare their trees.
746 Prompt for a revision of the current file, and visit it in a separate
747 buffer (@code{vc-revision-other-window}).
750 Display an annotated version of the current file: for each line, show
751 the latest revision in which it was modified (@code{vc-annotate}).
756 @kbd{C-x v =} (@code{vc-diff}) displays a @dfn{diff} which compares
757 each work file in the current VC fileset to the version(s) from which
758 you started editing. The diff is displayed in another window, in a
759 Diff mode buffer (@pxref{Diff Mode}) named @file{*vc-diff*}. The
760 usual Diff mode commands are available in this buffer. In particular,
761 the @kbd{g} (@code{revert-buffer}) command performs the file
762 comparison again, generating a new diff.
765 To compare two arbitrary revisions of the current VC fileset, call
766 @code{vc-diff} with a prefix argument: @kbd{C-u C-x v =}. This
767 prompts for two revision IDs (@pxref{VCS Concepts}), and displays a
768 diff between those versions of the fileset. This will not work
769 reliably for multi-file VC filesets, if the version control system is
770 file-based rather than changeset-based (e.g., CVS), since then
771 revision IDs for different files would not be related in any
774 Instead of the revision ID, some version control systems let you
775 specify revisions in other formats. For instance, under Bazaar you
776 can enter @samp{date:yesterday} for the argument to @kbd{C-u C-x v =}
777 (and related commands) to specify the first revision committed after
778 yesterday. See the documentation of the version control system for
781 If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a Dired buffer
782 (@pxref{Dired}), the file listed on the current line is treated as the
787 @kbd{M-x vc-ediff} works like @kbd{C-x v =}, except that it uses an
788 Ediff session. @xref{Top,, Ediff, ediff, The Ediff Manual}.
793 @kbd{C-x v D} (@code{vc-root-diff}) is similar to @kbd{C-x v =}, but
794 it displays the changes in the entire current working tree (i.e., the
795 working tree containing the current VC fileset). If you invoke this
796 command from a Dired buffer, it applies to the working tree containing
799 @vindex vc-diff-switches
800 You can customize the @command{diff} options that @kbd{C-x v =} and
801 @kbd{C-x v D} use for generating diffs. The options used are taken
802 from the first non-@code{nil} value amongst the variables
803 @code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches}, and
804 @code{diff-switches} (@pxref{Comparing Files}), in that order. Here,
805 @var{backend} stands for the relevant version control system,
806 e.g., @code{bzr} for Bazaar. Since @code{nil} means to check the
807 next variable in the sequence, either of the first two may use the
808 value @code{t} to mean no switches at all. Most of the
809 @code{vc-@var{backend}-diff-switches} variables default to @code{nil},
810 but some default to @code{t}; these are for version control systems
811 whose @code{diff} implementations do not accept common diff options,
814 @findex vc-revision-other-window
816 To directly examine an older version of a file, visit the work file
817 and type @kbd{C-x v ~ @var{revision} @key{RET}}
818 (@code{vc-revision-other-window}). This retrieves the file version
819 corresponding to @var{revision}, saves it to
820 @file{@var{filename}.~@var{revision}~}, and visits it in a separate
825 Many version control systems allow you to view files @dfn{annotated}
826 with per-line revision information, by typing @kbd{C-x v g}
827 (@code{vc-annotate}). This creates a new buffer (the ``annotate
828 buffer'') displaying the file's text, with each line colored to show
829 how old it is. Red text is new, blue is old, and intermediate colors
830 indicate intermediate ages. By default, the color is scaled over the
831 full range of ages, such that the oldest changes are blue, and the
832 newest changes are red.
834 When you give a prefix argument to this command, Emacs reads two
835 arguments using the minibuffer: the revision to display and annotate
836 (instead of the current file contents), and the time span in days the
837 color range should cover.
839 From the annotate buffer, these and other color scaling options are
840 available from the @samp{VC-Annotate} menu. In this buffer, you can
841 also use the following keys to browse the annotations of past revisions,
842 view diffs, or view log entries:
846 Annotate the previous revision, i.e., the revision before the one
847 currently annotated. A numeric prefix argument is a repeat count, so
848 @kbd{C-u 10 p} would take you back 10 revisions.
851 Annotate the next revision, i.e., the revision after the one
852 currently annotated. A numeric prefix argument is a repeat count.
855 Annotate the revision indicated by the current line.
858 Annotate the revision before the one indicated by the current line.
859 This is useful to see the state the file was in before the change on
860 the current line was made.
863 Show in a buffer the file revision indicated by the current line.
866 Display the diff between the current line's revision and the previous
867 revision. This is useful to see what the current line's revision
868 actually changed in the file.
871 Display the diff between the current line's revision and the previous
872 revision for all files in the changeset (for VC systems that support
873 changesets). This is useful to see what the current line's revision
874 actually changed in the tree.
877 Show the log of the current line's revision. This is useful to see
878 the author's description of the changes in the revision on the current
882 Annotate the working revision--the one you are editing. If you used
883 @kbd{p} and @kbd{n} to browse to other revisions, use this key to
884 return to your working revision.
887 Toggle the annotation visibility. This is useful for looking just at
888 the file contents without distraction from the annotations.
892 @subsection VC Change Log
896 Display the change history for the current fileset
897 (@code{vc-print-log}).
900 Display the change history for the current repository
901 (@code{vc-print-root-log}).
904 Display the changes that a pull operation will retrieve
905 (@code{vc-log-incoming}).
908 Display the changes that will be sent by the next push operation
909 (@code{vc-log-outgoing}).
914 @kbd{C-x v l} (@code{vc-print-log}) displays a buffer named
915 @file{*vc-change-log*}, showing the history of changes made to the
916 current file, including who made the changes, the dates, and the log
917 entry for each change (these are the same log entries you would enter
918 via the @file{*vc-log*} buffer; @pxref{Log Buffer}). Point is
919 centered at the revision of the file currently being visited. With a
920 prefix argument, the command prompts for the revision to center on,
921 and the maximum number of revisions to display.
923 If you call @kbd{C-x v l} from a VC Directory buffer (@pxref{VC
924 Directory Mode}) or a Dired buffer (@pxref{Dired}), it applies to the
925 file listed on the current line.
927 @findex vc-print-root-log
928 @findex log-view-toggle-entry-display
929 @kbd{C-x v L} (@code{vc-print-root-log}) displays a
930 @file{*vc-change-log*} buffer showing the history of the entire
931 version-controlled directory tree (RCS, SCCS, and CVS do not support
932 this feature). With a prefix argument, the command prompts for the
933 maximum number of revisions to display.
935 The @kbd{C-x v L} history is shown in a compact form, usually
936 showing only the first line of each log entry. However, you can type
937 @key{RET} (@code{log-view-toggle-entry-display}) in the
938 @file{*vc-change-log*} buffer to reveal the entire log entry for the
939 revision at point. A second @key{RET} hides it again.
941 On a decentralized version control system, the @kbd{C-x v I}
942 (@code{vc-log-incoming}) command displays a log buffer showing the
943 changes that will be applied, the next time you run the version
944 control system's ``pull'' command to get new revisions from another
945 repository (@pxref{VC Pull}). This other repository is the default
946 one from which changes are pulled, as defined by the version control
947 system; with a prefix argument, @code{vc-log-incoming} prompts for a
948 specific repository. Similarly, @kbd{C-x v O}
949 (@code{vc-log-outgoing}) shows the changes that will be sent to
950 another repository, the next time you run the ``push'' command; with a
951 prefix argument, it prompts for a specific destination repository.
953 In the @file{*vc-change-log*} buffer, you can use the following keys
954 to move between the logs of revisions and of files, and to examine and
955 compare past revisions (@pxref{Old Revisions}):
959 Move to the previous revision entry. (Revision entries in the log
960 buffer are usually in reverse-chronological order, so the previous
961 revision-item usually corresponds to a newer revision.) A numeric
962 prefix argument is a repeat count.
965 Move to the next revision entry. A numeric prefix argument is a
969 Move to the log of the previous file, if showing logs for a multi-file
970 VC fileset. Otherwise, just move to the beginning of the log. A
971 numeric prefix argument is a repeat count.
974 Move to the log of the next file, if showing logs for a multi-file VC
975 fileset. A numeric prefix argument is a repeat count.
978 Annotate the revision on the current line (@pxref{Old Revisions}).
981 Modify the change comment displayed at point. Note that not all VC
982 systems support modifying change comments.
985 Visit the revision indicated at the current line.
988 Display a diff between the revision at point and the next earlier
989 revision, for the specific file.
992 Display the changeset diff between the revision at point and the next
993 earlier revision. This shows the changes to all files made in that
997 In a compact-style log buffer (e.g., the one created by @kbd{C-x v
998 L}), toggle between showing and hiding the full log entry for the
1002 @vindex vc-log-show-limit
1003 Because fetching many log entries can be slow, the
1004 @file{*vc-change-log*} buffer displays no more than 2000 revisions by
1005 default. The variable @code{vc-log-show-limit} specifies this limit;
1006 if you set the value to zero, that removes the limit. You can also
1007 increase the number of revisions shown in an existing
1008 @file{*vc-change-log*} buffer by clicking on the @samp{Show 2X
1009 entries} or @samp{Show unlimited entries} buttons at the end of the
1010 buffer. However, RCS, SCCS, and CVS do not support this feature.
1013 @subsection Undoing Version Control Actions
1017 Revert the work file(s) in the current VC fileset to the last revision
1021 @c `C-x v c' (vc-rollback) was removed, since it's RCS/SCCS specific.
1025 @vindex vc-revert-show-diff
1026 If you want to discard all the changes you have made to the current
1027 VC fileset, type @kbd{C-x v u} (@code{vc-revert-buffer}). This shows
1028 you a diff between the work file(s) and the revision from which you
1029 started editing, and asks for confirmation for discarding the changes.
1030 If you agree, the fileset is reverted. If you don't want @kbd{C-x v
1031 u} to show a diff, set the variable @code{vc-revert-show-diff} to
1032 @code{nil} (you can still view the diff directly with @kbd{C-x v =};
1033 @pxref{Old Revisions}). Note that @kbd{C-x v u} cannot be reversed
1034 with the usual undo commands (@pxref{Undo}), so use it with care.
1036 On locking-based version control systems, @kbd{C-x v u} leaves files
1037 unlocked; you must lock again to resume editing. You can also use
1038 @kbd{C-x v u} to unlock a file if you lock it and then decide not to
1042 @subsection Ignore Version Control Files
1046 Ignore a file under current version control system. (@code{vc-ignore}).
1051 Many source trees contain some files that do not need to be
1052 versioned, such as editor backups, object or bytecode files, and built
1053 programs. You can simply not add them, but then they'll always crop
1054 up as unknown files. You can also tell the version control system to
1055 ignore these files by adding them to the ignore file at the top of the
1056 tree. @kbd{C-x v G} (@code{vc-ignore}) can help you do this. When
1057 called with a prefix argument, you can remove a file from the ignored
1060 @node VC Directory Mode
1061 @subsection VC Directory Mode
1063 @cindex VC Directory buffer
1064 The @dfn{VC Directory buffer} is a specialized buffer for viewing
1065 the version control statuses of the files in a directory tree, and
1066 performing version control operations on those files. In particular,
1067 it is used to specify multi-file VC filesets for commands like
1068 @w{@kbd{C-x v v}} to act on (@pxref{VC Directory Commands}).
1072 To use the VC Directory buffer, type @kbd{C-x v d} (@code{vc-dir}).
1073 This reads a directory name using the minibuffer, and switches to a VC
1074 Directory buffer for that directory. By default, the buffer is named
1075 @file{*vc-dir*}. Its contents are described
1080 in @ref{VC Directory Buffer}.
1083 The @code{vc-dir} command automatically detects the version control
1084 system to be used in the specified directory. In the event that more
1085 than one system is being used in the directory, you should invoke the
1086 command with a prefix argument, @kbd{C-u C-x v d}; this prompts for
1087 the version control system which the VC Directory buffer should use.
1092 @cindex CVS directory mode
1093 In addition to the VC Directory buffer, Emacs has a similar facility
1094 called PCL-CVS which is specialized for CVS@. @xref{Top, , About
1095 PCL-CVS, pcl-cvs, PCL-CVS---The Emacs Front-End to CVS}.
1099 * Buffer: VC Directory Buffer. What the buffer looks like and means.
1100 * Commands: VC Directory Commands. Commands to use in a VC directory buffer.
1103 @node VC Directory Buffer
1104 @subsubsection The VC Directory Buffer
1106 The VC Directory buffer contains a list of version-controlled files
1107 and their version control statuses. It lists files in the current
1108 directory (the one specified when you called @kbd{C-x v d}) and its
1109 subdirectories, but only those with a ``noteworthy'' status. Files
1110 that are up-to-date (i.e., the same as in the repository) are
1111 omitted. If all the files in a subdirectory are up-to-date, the
1112 subdirectory is not listed either. As an exception, if a file has
1113 become up-to-date as a direct result of a VC command, it is listed.
1115 Here is an example of a VC Directory buffer listing:
1122 unregistered temp.txt
1129 Two work files have been modified but not committed:
1130 @file{configure.ac} in the current directory, and @file{foo.c} in the
1131 @file{src/} subdirectory. The file named @file{README} has been added
1132 but is not yet committed, while @file{temp.txt} is not under version
1133 control (@pxref{Registering}).
1135 The @samp{*} characters next to the entries for @file{README} and
1136 @file{src/main.c} indicate that the user has marked out these files as
1137 the current VC fileset
1142 (@pxref{VC Directory Commands}).
1145 The above example is typical for a decentralized version control
1146 system like Bazaar, Git, or Mercurial. Other systems can show other
1147 statuses. For instance, CVS shows the @samp{needs-update} status if
1148 the repository has changes that have not been applied to the work
1149 file. RCS and SCCS show the name of the user locking a file as its
1153 @vindex vc-stay-local
1154 @vindex vc-cvs-stay-local
1155 On CVS and Subversion, the @code{vc-dir} command normally contacts
1156 the repository, which may be on a remote machine, to check for
1157 updates. If you change the variable @code{vc-stay-local} or
1158 @code{vc-cvs-stay-local} (for CVS) to @code{nil} (@pxref{CVS
1159 Options}), then Emacs avoids contacting a remote repository when
1160 generating the VC Directory buffer (it will still contact it when
1161 necessary, e.g., when doing a commit). This may be desirable if you
1162 are working offline or the network is slow.
1165 @vindex vc-directory-exclusion-list
1166 The VC Directory buffer omits subdirectories listed in the variable
1167 @code{vc-directory-exclusion-list}. Its default value contains
1168 directories that are used internally by version control systems.
1170 @node VC Directory Commands
1171 @subsubsection VC Directory Commands
1173 Emacs provides several commands for navigating the VC Directory
1174 buffer, and for ``marking'' files as belonging to the current VC
1180 Move point to the next entry (@code{vc-dir-next-line}).
1183 Move point to the previous entry (@code{vc-dir-previous-line}).
1186 Move to the next directory entry (@code{vc-dir-next-directory}).
1189 Move to the previous directory entry
1190 (@code{vc-dir-previous-directory}).
1194 Visit the file or directory listed on the current line
1195 (@code{vc-dir-find-file}).
1198 Visit the file or directory on the current line, in a separate window
1199 (@code{vc-dir-find-file-other-window}).
1202 Mark the file or directory on the current line (@code{vc-dir-mark}),
1203 putting it in the current VC fileset. If the region is active, mark
1204 all files in the region.
1206 A file cannot be marked with this command if it is already in a marked
1207 directory, or one of its subdirectories. Similarly, a directory
1208 cannot be marked with this command if any file in its tree is marked.
1211 If point is on a file entry, mark all files with the same status; if
1212 point is on a directory entry, mark all files in that directory tree
1213 (@code{vc-dir-mark-all-files}). With a prefix argument, mark all
1214 listed files and directories.
1217 Quit the VC Directory buffer, and bury it (@code{quit-window}).
1220 Unmark the file or directory on the current line. If the region is
1221 active, unmark all the files in the region (@code{vc-dir-unmark}).
1224 If point is on a file entry, unmark all files with the same status; if
1225 point is on a directory entry, unmark all files in that directory tree
1226 (@code{vc-dir-unmark-all-files}). With a prefix argument, unmark all
1227 files and directories.
1230 Hide files with @samp{up-to-date} status
1231 (@code{vc-dir-hide-up-to-date}). With a prefix argument, hide items
1232 whose state is that of the item at point.
1236 @findex vc-dir-mark-all-files
1237 While in the VC Directory buffer, all the files that you mark with
1238 @kbd{m} (@code{vc-dir-mark}) or @kbd{M} (@code{vc-dir-mark}) are in
1239 the current VC fileset. If you mark a directory entry with @kbd{m},
1240 all the listed files in that directory tree are in the current VC
1241 fileset. The files and directories that belong to the current VC
1242 fileset are indicated with a @samp{*} character in the VC Directory
1243 buffer, next to their VC status. In this way, you can set up a
1244 multi-file VC fileset to be acted on by VC commands like @w{@kbd{C-x v
1245 v}} (@pxref{Basic VC Editing}), @w{@kbd{C-x v =}} (@pxref{Old
1246 Revisions}), and @w{@kbd{C-x v u}} (@pxref{VC Undo}).
1248 The VC Directory buffer also defines some single-key shortcuts for
1249 VC commands with the @kbd{C-x v} prefix: @kbd{=}, @kbd{+}, @kbd{l},
1250 @kbd{i}, @kbd{D}, @kbd{L}, @kbd{G}, @kbd{I} and @kbd{v}.
1252 For example, you can commit a set of edited files by opening a VC
1253 Directory buffer, where the files are listed with the @samp{edited}
1254 status; marking the files; and typing @kbd{v} or @kbd{C-x v v}
1255 (@code{vc-next-action}). If the version control system is
1256 changeset-based, Emacs will commit the files in a single revision.
1258 While in the VC Directory buffer, you can also perform search and
1259 replace on the current VC fileset, with the following commands:
1263 Search the fileset (@code{vc-dir-search}).
1266 Do a regular expression query replace on the fileset
1267 (@code{vc-dir-query-replace-regexp}).
1270 Do an incremental search on the fileset (@code{vc-dir-isearch}).
1273 Do an incremental regular expression search on the fileset
1274 (@code{vc-dir-isearch-regexp}).
1278 Apart from acting on multiple files, these commands behave much like
1279 their single-buffer counterparts (@pxref{Search}).
1281 @cindex stashes in version control
1282 @cindex shelves in version control
1283 The above commands are also available via the menu bar, and via a
1284 context menu invoked by @kbd{Mouse-2}. Furthermore, some VC backends
1285 use the menu to provide extra backend-specific commands. For example,
1286 Git and Bazaar allow you to manipulate @dfn{stashes} and @dfn{shelves}
1287 (where are a way to temporarily put aside uncommitted changes, and
1288 bring them back at a later time).
1291 @subsection Version Control Branches
1292 @cindex branch (version control)
1294 One use of version control is to support multiple independent lines
1295 of development, which are called @dfn{branches}. Amongst other
1296 things, branches can be used for maintaining separate ``stable'' and
1297 ``development'' versions of a program, and for developing unrelated
1298 features in isolation from one another.
1300 VC's support for branch operations is currently fairly limited. For
1301 decentralized version control systems, it provides commands for
1302 @dfn{updating} one branch with the contents of another, and for
1303 @dfn{merging} the changes made to two different branches
1304 (@pxref{Merging}). For centralized version control systems, it
1305 supports checking out different branches and committing into new or
1309 * Switching Branches:: How to get to another existing branch.
1310 * VC Pull:: Updating the contents of a branch.
1311 * Merging:: Transferring changes between branches.
1312 * Creating Branches:: How to start a new branch.
1315 @node Switching Branches
1316 @subsubsection Switching between Branches
1318 The various version control systems differ in how branches are
1319 implemented, and these differences cannot be entirely concealed by VC.
1321 On some decentralized version control systems, including Bazaar and
1322 Mercurial in its normal mode of operation, each branch has its own
1323 working directory tree, so switching between branches just involves
1324 switching directories. On Git, branches are normally @dfn{co-located}
1325 in the same directory, and switching between branches is done using
1326 the @command{git checkout} command, which changes the contents of the
1327 working tree to match the branch you switch to. Bazaar also supports
1328 co-located branches, in which case the @command{bzr switch} command
1329 will switch branches in the current directory. With Subversion, you
1330 switch to another branch using the @command{svn switch} command.
1332 The VC command to switch to another branch in the current directory
1333 is @kbd{C-x v r @var{branch-name} @key{RET}} (@code{vc-retrieve-tag}).
1335 On centralized version control systems, you can also switch between
1336 branches by typing @kbd{C-u C-x v v} in an up-to-date work file
1337 (@pxref{Advanced C-x v v}), and entering the revision ID for a
1338 revision on another branch. On CVS, for instance, revisions on the
1339 @dfn{trunk} (the main line of development) normally have IDs of the
1340 form 1.1, 1.2, 1.3, @dots{}, while the first branch created from (say)
1341 revision 1.2 has revision IDs 1.2.1.1, 1.2.1.2, @dots{}, the second
1342 branch created from revision 1.2 has revision IDs 1.2.2.1, 1.2.2.2,
1343 @dots{}, and so forth. You can also specify the @dfn{branch ID},
1344 which is a branch revision ID omitting its final component
1345 (e.g., 1.2.1), to switch to the latest revision on that branch.
1347 On a locking-based system, switching to a different branch also
1348 unlocks (write-protects) the working tree.
1350 Once you have switched to a branch, VC commands will apply to that
1351 branch until you switch away; for instance, any VC filesets that you
1352 commit will be committed to that specific branch.
1355 @subsubsection Pulling Changes into a Branch
1359 On a decentralized version control system, update the current branch
1360 by ``pulling in'' changes from another location.
1362 On a centralized version control system, update the current VC
1368 On a decentralized version control system, the command @kbd{C-x v +}
1369 (@code{vc-pull}) updates the current branch and working tree. It is
1370 typically used to update a copy of a remote branch. If you supply a
1371 prefix argument, the command prompts for the exact version control
1372 command to use, which lets you specify where to pull changes from.
1373 Otherwise, it pulls from a default location determined by the version
1376 Amongst decentralized version control systems, @kbd{C-x v +} is
1377 currently supported only by Bazaar, Git, and Mercurial. On Bazaar, it
1378 calls @command{bzr pull} for ordinary branches (to pull from a master
1379 branch into a mirroring branch), and @command{bzr update} for a bound
1380 branch (to pull from a central repository). On Git, it calls
1381 @command{git pull} to fetch changes from a remote repository and merge
1382 it into the current branch. On Mercurial, it calls @command{hg pull
1383 -u} to fetch changesets from the default remote repository and update
1384 the working directory.
1386 Prior to pulling, you can use @kbd{C-x v I} (@code{vc-log-incoming})
1387 to view a log buffer of the changes to be applied. @xref{VC Change
1390 On a centralized version control system like CVS, @kbd{C-x v +}
1391 updates the current VC fileset from the repository.
1394 @subsubsection Merging Branches
1395 @cindex merging changes
1399 On a decentralized version control system, merge changes from another
1400 branch into the current one.
1402 On a centralized version control system, merge changes from another
1403 branch into the current VC fileset.
1406 While developing a branch, you may sometimes need to @dfn{merge} in
1407 changes that have already been made in another branch. This is not a
1408 trivial operation, as overlapping changes may have been made to the
1411 On a decentralized version control system, merging is done with the
1412 command @kbd{C-x v m} (@code{vc-merge}). On Bazaar, this prompts for
1413 the exact arguments to pass to @command{bzr merge}, offering a
1414 sensible default if possible. On Git, this prompts for the name of a
1415 branch to merge from, with completion (based on the branch names known
1416 to the current repository). The output from running the merge command
1417 is shown in a separate buffer.
1419 On a centralized version control system like CVS, @kbd{C-x v m}
1420 prompts for a branch ID, or a pair of revision IDs (@pxref{Switching
1421 Branches}); then it finds the changes from that branch, or the changes
1422 between the two revisions you specified, and merges those changes into
1423 the current VC fileset. If you just type @key{RET}, Emacs simply
1424 merges any changes that were made on the same branch since you checked
1428 @cindex resolving conflicts
1429 Immediately after performing a merge, only the working tree is
1430 modified, and you can review the changes produced by the merge with
1431 @kbd{C-x v D} and related commands (@pxref{Old Revisions}). If the
1432 two branches contained overlapping changes, merging produces a
1433 @dfn{conflict}; a warning appears in the output of the merge command,
1434 and @dfn{conflict markers} are inserted into each affected work file,
1435 surrounding the two sets of conflicting changes. You must then
1436 resolve the conflict by editing the conflicted files. Once you are
1437 done, the modified files must be committed in the usual way for the
1438 merge to take effect (@pxref{Basic VC Editing}).
1440 @node Creating Branches
1441 @subsubsection Creating New Branches
1443 On centralized version control systems like CVS, Emacs supports
1444 creating new branches as part of a commit operation. When committing
1445 a modified VC fileset, type @kbd{C-u C-x v v} (@code{vc-next-action}
1446 with a prefix argument; @pxref{Advanced C-x v v}). Then Emacs prompts
1447 for a revision ID for the new revision. You should specify a suitable
1448 branch ID for a branch starting at the current revision. For example,
1449 if the current revision is 2.5, the branch ID should be 2.5.1, 2.5.2,
1450 and so on, depending on the number of existing branches at that point.
1452 To create a new branch at an older revision (one that is no longer
1453 the head of a branch), first select that revision (@pxref{Switching
1454 Branches}). Your procedure will then differ depending on whether you
1455 are using a locking or merging-based VCS.
1457 On a locking VCS, you will need to lock the old revision branch with
1458 @kbd{C-x v v}. You'll be asked to confirm, when you lock the old
1459 revision, that you really mean to create a new branch---if you say no,
1460 you'll be offered a chance to lock the latest revision instead. On a
1461 merging-based VCS you will skip this step.
1463 Then make your changes and type @kbd{C-x v v} again to commit a new
1464 revision. This creates a new branch starting from the selected
1467 After the branch is created, subsequent commits create new revisions
1468 on that branch. To leave the branch, you must explicitly select a
1469 different revision with @kbd{C-u C-x v v}.
1472 @include vc1-xtra.texi
1476 @section Change Logs
1479 Many software projects keep a @dfn{change log}. This is a file,
1480 normally named @file{ChangeLog}, containing a chronological record of
1481 when and how the program was changed. Sometimes, these files are
1482 automatically generated from the change log entries stored in version
1483 control systems, or are used to generate these change log entries.
1484 Sometimes, there are several change log files, each recording the
1485 changes in one directory or directory tree.
1488 * Change Log Commands:: Commands for editing change log files.
1489 * Format of ChangeLog:: What the change log file looks like.
1492 @node Change Log Commands
1493 @subsection Change Log Commands
1496 @findex add-change-log-entry-other-window
1497 The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
1498 file for the file you are editing
1499 (@code{add-change-log-entry-other-window}). If that file is actually
1500 a backup file, it makes an entry appropriate for the file's
1501 parent---that is useful for making log entries for functions that
1502 have been deleted in the current version.
1504 @kbd{C-x 4 a} visits the change log file and creates a new entry
1505 unless the most recent entry is for today's date and your name. It
1506 also creates a new item for the current file. For many languages, it
1507 can even guess the name of the function or other object that was
1510 @vindex add-log-keep-changes-together
1511 When the variable @code{add-log-keep-changes-together} is
1512 non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file
1513 rather than starting a new item.
1515 You can combine multiple changes of the same nature. If you don't
1516 enter any text after the initial @kbd{C-x 4 a}, any subsequent
1517 @kbd{C-x 4 a} adds another symbol to the change log entry.
1519 @vindex add-log-always-start-new-record
1520 If @code{add-log-always-start-new-record} is non-@code{nil},
1521 @kbd{C-x 4 a} always makes a new entry, even if the last entry
1522 was made by you and on the same date.
1524 @vindex change-log-version-info-enabled
1525 @vindex change-log-version-number-regexp-list
1526 @cindex file version in change log entries
1527 If the value of the variable @code{change-log-version-info-enabled}
1528 is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the
1529 change log entry. It finds the version number by searching the first
1530 ten percent of the file, using regular expressions from the variable
1531 @code{change-log-version-number-regexp-list}.
1533 @cindex Change Log mode
1534 @findex change-log-mode
1535 The change log file is visited in Change Log mode. In this major
1536 mode, each bunch of grouped items counts as one paragraph, and each
1537 entry is considered a page. This facilitates editing the entries.
1538 @kbd{C-j} and auto-fill indent each new line like the previous line;
1539 this is convenient for entering the contents of an entry.
1541 You can use the @code{next-error} command (by default bound to
1542 @kbd{C-x `}) to move between entries in the Change Log, when Change
1543 Log mode is on. You will jump to the actual site in the file that was
1544 changed, not just to the next Change Log entry. You can also use
1545 @code{previous-error} to move back in the same list.
1547 @findex change-log-merge
1548 You can use the command @kbd{M-x change-log-merge} to merge other
1549 log files into a buffer in Change Log Mode, preserving the date
1550 ordering of entries.
1552 Version control systems are another way to keep track of changes in
1553 your program and keep a change log. In the VC log buffer, typing
1554 @kbd{C-c C-a} (@code{log-edit-insert-changelog}) inserts the relevant
1555 Change Log entry, if one exists. @xref{Log Buffer}.
1557 @node Format of ChangeLog
1558 @subsection Format of ChangeLog
1560 A change log entry starts with a header line that contains the
1561 current date, your name (taken from the variable
1562 @code{add-log-full-name}), and your email address (taken from the
1563 variable @code{add-log-mailing-address}). Aside from these header
1564 lines, every line in the change log starts with a space or a tab. The
1565 bulk of the entry consists of @dfn{items}, each of which starts with a
1566 line starting with whitespace and a star. Here are two entries, both
1567 dated in May 1993, with two items and one item respectively.
1573 1993-05-25 Richard Stallman <rms@@gnu.org>
1575 * man.el: Rename symbols `man-*' to `Man-*'.
1576 (manual-entry): Make prompt string clearer.
1578 * simple.el (blink-matching-paren-distance):
1579 Change default to 12,000.
1581 1993-05-24 Richard Stallman <rms@@gnu.org>
1583 * vc.el (minor-mode-map-alist): Don't use it if it's void.
1584 (vc-cancel-version): Doc fix.
1587 One entry can describe several changes; each change should have its
1588 own item, or its own line in an item. Normally there should be a
1589 blank line between items. When items are related (parts of the same
1590 change, in different places), group them by leaving no blank line
1593 You should put a copyright notice and permission notice at the
1594 end of the change log file. Here is an example:
1597 Copyright 1997, 1998 Free Software Foundation, Inc.
1598 Copying and distribution of this file, with or without modification, are
1599 permitted provided the copyright notice and this notice are preserved.
1603 Of course, you should substitute the proper years and copyright holder.
1606 @section Tags Tables
1607 @cindex tags and tag tables
1609 A @dfn{tag} is a reference to a subunit in a program or in a
1610 document. In source code, tags reference syntactic elements of the
1611 program: functions, subroutines, data types, macros, etc. In a
1612 document, tags reference chapters, sections, appendices, etc. Each
1613 tag specifies the name of the file where the corresponding subunit is
1614 defined, and the position of the subunit's definition in that file.
1616 A @dfn{tags table} records the tags extracted by scanning the source
1617 code of a certain program or a certain document. Tags extracted from
1618 generated files reference the original files, rather than the
1619 generated files that were scanned during tag extraction. Examples of
1620 generated files include C files generated from Cweb source files, from
1621 a Yacc parser, or from Lex scanner definitions; @file{.i} preprocessed
1622 C files; and Fortran files produced by preprocessing @file{.fpp}
1626 To produce a tags table, you run the @command{etags} shell command
1627 on a document or the source code file. The @samp{etags} program
1628 writes the tags to a @dfn{tags table file}, or @dfn{tags file} in
1629 short. The conventional name for a tags file is @file{TAGS}@.
1630 @xref{Create Tags Table}.
1632 Emacs provides many commands for searching and replacing using the
1633 information recorded in tags tables. For instance, the @kbd{M-.}
1634 (@code{find-tag}) jumps to the location of a specified function
1635 definition in its source file. @xref{Find Tag}.
1637 @cindex C++ class browser, tags
1639 @cindex class browser, C++
1641 The Ebrowse facility is similar to @command{etags} but specifically
1642 tailored for C++. @xref{Top,, Ebrowse, ebrowse, Ebrowse User's
1643 Manual}. The Semantic package provides another way to generate and
1644 use tags, separate from the @command{etags} facility.
1648 * Tag Syntax:: Tag syntax for various types of code and text files.
1649 * Create Tags Table:: Creating a tags table with @command{etags}.
1650 * Etags Regexps:: Create arbitrary tags using regular expressions.
1651 * Select Tags Table:: How to visit a tags table.
1652 * Find Tag:: Commands to find the definition of a specific tag.
1653 * Tags Search:: Using a tags table for searching and replacing.
1654 * List Tags:: Using tags for completion, and listing them.
1658 @subsection Source File Tag Syntax
1660 Here is how tag syntax is defined for the most popular languages:
1664 In C code, any C function or typedef is a tag, and so are definitions of
1665 @code{struct}, @code{union} and @code{enum}.
1666 @code{#define} macro definitions, @code{#undef} and @code{enum}
1668 tags, unless you specify @samp{--no-defines} when making the tags table.
1669 Similarly, global variables are tags, unless you specify
1670 @samp{--no-globals}, and so are struct members, unless you specify
1671 @samp{--no-members}. Use of @samp{--no-globals}, @samp{--no-defines}
1672 and @samp{--no-members} can make the tags table file much smaller.
1674 You can tag function declarations and external variables in addition
1675 to function definitions by giving the @samp{--declarations} option to
1679 In C++ code, in addition to all the tag constructs of C code, member
1680 functions are also recognized; member variables are also recognized,
1681 unless you use the @samp{--no-members} option. Tags for variables and
1682 functions in classes are named @samp{@var{class}::@var{variable}} and
1683 @samp{@var{class}::@var{function}}. @code{operator} definitions have
1684 tag names like @samp{operator+}.
1687 In Java code, tags include all the constructs recognized in C++, plus
1688 the @code{interface}, @code{extends} and @code{implements} constructs.
1689 Tags for variables and functions in classes are named
1690 @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
1693 In @LaTeX{} documents, the arguments for @code{\chapter},
1694 @code{\section}, @code{\subsection}, @code{\subsubsection},
1695 @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite},
1696 @code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry},
1697 @code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand},
1698 @code{\newenvironment} and @code{\renewenvironment} are tags.
1700 Other commands can make tags as well, if you specify them in the
1701 environment variable @env{TEXTAGS} before invoking @command{etags}. The
1702 value of this environment variable should be a colon-separated list of
1703 command names. For example,
1706 TEXTAGS="mycommand:myothercommand"
1711 specifies (using Bourne shell syntax) that the commands
1712 @samp{\mycommand} and @samp{\myothercommand} also define tags.
1715 In Lisp code, any function defined with @code{defun}, any variable
1716 defined with @code{defvar} or @code{defconst}, and in general the
1717 first argument of any expression that starts with @samp{(def} in
1718 column zero is a tag. As an exception, expressions of the form
1719 @code{(defvar @var{foo})} are treated as declarations, and are only
1720 tagged if the @samp{--declarations} option is given.
1723 In Scheme code, tags include anything defined with @code{def} or with a
1724 construct whose name starts with @samp{def}. They also include variables
1725 set with @code{set!} at top level in the file.
1728 Several other languages are also supported:
1733 In Ada code, functions, procedures, packages, tasks and types are
1734 tags. Use the @samp{--packages-only} option to create tags for
1737 In Ada, the same name can be used for different kinds of entity
1738 (e.g., for a procedure and for a function). Also, for things like
1739 packages, procedures and functions, there is the spec (i.e., the
1740 interface) and the body (i.e., the implementation). To make it
1741 easier to pick the definition you want, Ada tag name have suffixes
1742 indicating the type of entity:
1759 Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
1760 directly to the body of the package @code{bidule}, while @kbd{M-x
1761 find-tag @key{RET} bidule @key{RET}} will just search for any tag
1765 In assembler code, labels appearing at the start of a line,
1766 followed by a colon, are tags.
1769 In Bison or Yacc input files, each rule defines as a tag the nonterminal
1770 it constructs. The portions of the file that contain C code are parsed
1774 In Cobol code, tags are paragraph names; that is, any word starting in
1775 column 8 and followed by a period.
1778 In Erlang code, the tags are the functions, records and macros defined
1782 In Fortran code, functions, subroutines and block data are tags.
1785 In HTML input files, the tags are the @code{title} and the @code{h1},
1786 @code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchors
1787 and all occurrences of @code{id=}.
1790 In Lua input files, all functions are tags.
1793 In makefiles, targets are tags; additionally, variables are tags
1794 unless you specify @samp{--no-globals}.
1797 In Objective C code, tags include Objective C definitions for classes,
1798 class categories, methods and protocols. Tags for variables and
1799 functions in classes are named @samp{@var{class}::@var{variable}} and
1800 @samp{@var{class}::@var{function}}.
1803 In Pascal code, the tags are the functions and procedures defined in
1807 In Perl code, the tags are the packages, subroutines and variables
1808 defined by the @code{package}, @code{sub}, @code{use constant},
1809 @code{my}, and @code{local} keywords. Use @samp{--globals} if you
1810 want to tag global variables. Tags for subroutines are named
1811 @samp{@var{package}::@var{sub}}. The name for subroutines defined in
1812 the default package is @samp{main::@var{sub}}.
1815 In PHP code, tags are functions, classes and defines. Vars are tags
1816 too, unless you use the @samp{--no-members} option.
1819 In PostScript code, the tags are the functions.
1822 In Prolog code, tags are predicates and rules at the beginning of
1826 In Python code, @code{def} or @code{class} at the beginning of a line
1830 You can also generate tags based on regexp matching (@pxref{Etags
1831 Regexps}) to handle other formats and languages.
1833 @node Create Tags Table
1834 @subsection Creating Tags Tables
1835 @cindex @command{etags} program
1837 The @command{etags} program is used to create a tags table file. It knows
1838 the syntax of several languages, as described in
1840 the previous section.
1845 Here is how to run @command{etags}:
1848 etags @var{inputfiles}@dots{}
1852 The @command{etags} program reads the specified files, and writes a tags
1853 table named @file{TAGS} in the current working directory. You can
1854 optionally specify a different file name for the tags table by using the
1855 @samp{--output=@var{file}} option; specifying @file{-} as a file name
1856 prints the tags table to standard output.
1858 If the specified files don't exist, @command{etags} looks for
1859 compressed versions of them and uncompresses them to read them. Under
1860 MS-DOS, @command{etags} also looks for file names like @file{mycode.cgz}
1861 if it is given @samp{mycode.c} on the command line and @file{mycode.c}
1864 If the tags table becomes outdated due to changes in the files
1865 described in it, you can update it by running the @command{etags}
1866 program again. If the tags table does not record a tag, or records it
1867 for the wrong file, then Emacs will not be able to find that
1868 definition until you update the tags table. But if the position
1869 recorded in the tags table becomes a little bit wrong (due to other
1870 editing), Emacs will still be able to find the right position, with a
1873 Thus, there is no need to update the tags table after each edit.
1874 You should update a tags table when you define new tags that you want
1875 to have listed, or when you move tag definitions from one file to
1876 another, or when changes become substantial.
1878 You can make a tags table @dfn{include} another tags table, by
1879 passing the @samp{--include=@var{file}} option to @command{etags}. It
1880 then covers all the files covered by the included tags file, as well
1883 If you specify the source files with relative file names when you run
1884 @command{etags}, the tags file will contain file names relative to the
1885 directory where the tags file was initially written. This way, you can
1886 move an entire directory tree containing both the tags file and the
1887 source files, and the tags file will still refer correctly to the source
1888 files. If the tags file is @file{-} or is in the @file{/dev} directory,
1889 however, the file names are
1890 made relative to the current working directory. This is useful, for
1891 example, when writing the tags to @file{/dev/stdout}.
1893 When using a relative file name, it should not be a symbolic link
1894 pointing to a tags file in a different directory, because this would
1895 generally render the file names invalid.
1897 If you specify absolute file names as arguments to @command{etags}, then
1898 the tags file will contain absolute file names. This way, the tags file
1899 will still refer to the same files even if you move it, as long as the
1900 source files remain in the same place. Absolute file names start with
1901 @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
1903 When you want to make a tags table from a great number of files,
1904 you may have problems listing them on the command line, because some
1905 systems have a limit on its length. You can circumvent this limit by
1906 telling @command{etags} to read the file names from its standard
1907 input, by typing a dash in place of the file names, like this:
1910 find . -name "*.[chCH]" -print | etags -
1913 @command{etags} recognizes the language used in an input file based
1914 on its file name and contents. You can specify the language
1915 explicitly with the @samp{--language=@var{name}} option. You can
1916 intermix these options with file names; each one applies to the file
1917 names that follow it. Specify @samp{--language=auto} to tell
1918 @command{etags} to resume guessing the language from the file names
1919 and file contents. Specify @samp{--language=none} to turn off
1920 language-specific processing entirely; then @command{etags} recognizes
1921 tags by regexp matching alone (@pxref{Etags Regexps}).
1923 The option @samp{--parse-stdin=@var{file}} is mostly useful when
1924 calling @command{etags} from programs. It can be used (only once) in
1925 place of a file name on the command line. @command{etags} will read from
1926 standard input and mark the produced tags as belonging to the file
1929 @samp{etags --help} outputs the list of the languages @command{etags}
1930 knows, and the file name rules for guessing the language. It also prints
1931 a list of all the available @command{etags} options, together with a short
1932 explanation. If followed by one or more @samp{--language=@var{lang}}
1933 options, it outputs detailed information about how tags are generated for
1937 @subsection Etags Regexps
1939 The @samp{--regex} option to @command{etags} allows tags to be
1940 recognized by regular expression matching. You can intermix this
1941 option with file names; each one applies to the source files that
1942 follow it. If you specify multiple @samp{--regex} options, all of
1943 them are used in parallel. The syntax is:
1946 --regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers}
1950 The essential part of the option value is @var{tagregexp}, the regexp
1951 for matching tags. It is always used anchored, that is, it only
1952 matches at the beginning of a line. If you want to allow indented
1953 tags, use a regexp that matches initial whitespace; start it with
1956 In these regular expressions, @samp{\} quotes the next character, and
1957 all the GCC character escape sequences are supported (@samp{\a} for
1958 bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for
1959 escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for
1960 carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab).
1962 Ideally, @var{tagregexp} should not match more characters than are
1963 needed to recognize what you want to tag. If the syntax requires you
1964 to write @var{tagregexp} so it matches more characters beyond the tag
1965 itself, you should add a @var{nameregexp}, to pick out just the tag.
1966 This will enable Emacs to find tags more accurately and to do
1967 completion on tag names more reliably. You can find some examples
1970 The @var{modifiers} are a sequence of zero or more characters that
1971 modify the way @command{etags} does the matching. A regexp with no
1972 modifiers is applied sequentially to each line of the input file, in a
1973 case-sensitive way. The modifiers and their meanings are:
1977 Ignore case when matching this regexp.
1979 Match this regular expression against the whole file, so that
1980 multi-line matches are possible.
1982 Match this regular expression against the whole file, and allow
1983 @samp{.} in @var{tagregexp} to match newlines.
1986 The @samp{-R} option cancels all the regexps defined by preceding
1987 @samp{--regex} options. It too applies to the file names following
1988 it. Here's an example:
1991 etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
1992 bar.ber -R --lang=lisp los.er
1996 Here @command{etags} chooses the parsing language for @file{voo.doo} and
1997 @file{bar.ber} according to their contents. @command{etags} also uses
1998 @var{reg1} to recognize additional tags in @file{voo.doo}, and both
1999 @var{reg1} and @var{reg2} to recognize additional tags in
2000 @file{bar.ber}. @var{reg1} is checked against each line of
2001 @file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while
2002 @var{reg2} is checked against the whole @file{bar.ber} file,
2003 permitting multi-line matches, in a case-sensitive way. @command{etags}
2004 uses only the Lisp tags rules, with no user-specified regexp matching,
2005 to recognize tags in @file{los.er}.
2007 You can restrict a @samp{--regex} option to match only files of a
2008 given language by using the optional prefix @var{@{language@}}.
2009 (@samp{etags --help} prints the list of languages recognized by
2010 @command{etags}.) This is particularly useful when storing many
2011 predefined regular expressions for @command{etags} in a file. The
2012 following example tags the @code{DEFVAR} macros in the Emacs source
2013 files, for the C language only:
2016 --regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
2020 When you have complex regular expressions, you can store the list of
2021 them in a file. The following option syntax instructs @command{etags} to
2022 read two files of regular expressions. The regular expressions
2023 contained in the second file are matched without regard to case.
2026 --regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file}
2030 A regex file for @command{etags} contains one regular expression per
2031 line. Empty lines, and lines beginning with space or tab are ignored.
2032 When the first character in a line is @samp{@@}, @command{etags} assumes
2033 that the rest of the line is the name of another file of regular
2034 expressions; thus, one such file can include another file. All the
2035 other lines are taken to be regular expressions. If the first
2036 non-whitespace text on the line is @samp{--}, that line is a comment.
2038 For example, we can create a file called @samp{emacs.tags} with the
2042 -- This is for GNU Emacs C source files
2043 @{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
2047 and then use it like this:
2050 etags --regex=@@emacs.tags *.[ch] */*.[ch]
2053 Here are some more examples. The regexps are quoted to protect them
2054 from shell interpretation.
2062 etags --language=none \
2063 --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
2064 --regex='/###key \(.*\)/\1/' \
2065 --regex='/[ \t]*global[ \t].*/' \
2070 Note that tags are not generated for scripts, so that you have to add
2071 a line by yourself of the form @samp{###key @var{scriptname}} if you
2078 etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
2085 etags --language=none \
2086 --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
2087 --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
2088 \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
2092 @node Select Tags Table
2093 @subsection Selecting a Tags Table
2095 @findex visit-tags-table
2096 Emacs has at any time one @dfn{selected} tags table. All the
2097 commands for working with tags tables use the selected one. To select
2098 a tags table, type @kbd{M-x visit-tags-table}, which reads the tags
2099 table file name as an argument, with @file{TAGS} in the default
2100 directory as the default.
2102 @vindex tags-file-name
2103 Emacs does not actually read in the tags table contents until you
2104 try to use them; all @code{visit-tags-table} does is store the file
2105 name in the variable @code{tags-file-name}, and setting the variable
2106 yourself is just as good. The variable's initial value is @code{nil};
2107 that value tells all the commands for working with tags tables that
2108 they must ask for a tags table file name to use.
2110 Using @code{visit-tags-table} when a tags table is already loaded
2111 gives you a choice: you can add the new tags table to the current list
2112 of tags tables, or start a new list. The tags commands use all the tags
2113 tables in the current list. If you start a new list, the new tags table
2114 is used @emph{instead} of others. If you add the new table to the
2115 current list, it is used @emph{as well as} the others.
2117 @vindex tags-table-list
2118 You can specify a precise list of tags tables by setting the variable
2119 @code{tags-table-list} to a list of strings, like this:
2121 @c keep this on two lines for formatting in smallbook
2124 (setq tags-table-list
2125 '("~/emacs" "/usr/local/lib/emacs/src"))
2130 This tells the tags commands to look at the @file{TAGS} files in your
2131 @file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
2132 directory. The order depends on which file you are in and which tags
2133 table mentions that file, as explained above.
2135 Do not set both @code{tags-file-name} and @code{tags-table-list}.
2138 @subsection Finding a Tag
2140 The most important thing that a tags table enables you to do is to find
2141 the definition of a specific tag.
2144 @item M-.@: @var{tag} @key{RET}
2145 Find first definition of @var{tag} (@code{find-tag}).
2147 Find next alternate definition of last tag specified.
2149 Go back to previous tag found.
2150 @item C-M-. @var{pattern} @key{RET}
2151 Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
2153 Find the next tag whose name matches the last pattern used.
2154 @item C-x 4 .@: @var{tag} @key{RET}
2155 Find first definition of @var{tag}, but display it in another window
2156 (@code{find-tag-other-window}).
2157 @item C-x 5 .@: @var{tag} @key{RET}
2158 Find first definition of @var{tag}, and create a new frame to select the
2159 buffer (@code{find-tag-other-frame}).
2161 Pop back to where you previously invoked @kbd{M-.} and friends.
2166 @kbd{M-.}@: (@code{find-tag}) prompts for a tag name and jumps to
2167 its source definition. It works by searching through the tags table
2168 for that tag's file and approximate character position, visiting that
2169 file, and searching for the tag definition at ever-increasing
2170 distances away from the recorded approximate position.
2172 When entering the tag argument to @kbd{M-.}, the usual minibuffer
2173 completion commands can be used (@pxref{Completion}), with the tag
2174 names in the selected tags table as completion candidates. If you
2175 specify an empty argument, the balanced expression in the buffer
2176 before or around point is the default argument. @xref{Expressions}.
2178 You don't need to give @kbd{M-.} the full name of the tag; a part
2179 will do. @kbd{M-.} finds tags which contain that argument as a
2180 substring. However, it prefers an exact match to a substring match.
2181 To find other tags that match the same substring, give @code{find-tag}
2182 a numeric argument, as in @kbd{C-u M-.} or @kbd{M-0 M-.}; this does
2183 not read a tag name, but continues searching the tags table's text for
2184 another tag containing the same substring last used.
2187 @findex find-tag-other-window
2189 @findex find-tag-other-frame
2190 Like most commands that can switch buffers, @code{find-tag} has a
2191 variant that displays the new buffer in another window, and one that
2192 makes a new frame for it. The former is @w{@kbd{C-x 4 .}}
2193 (@code{find-tag-other-window}), and the latter is @w{@kbd{C-x 5 .}}
2194 (@code{find-tag-other-frame}).
2196 To move back to previous tag definitions, use @kbd{C-u - M-.}; more
2197 generally, @kbd{M-.} with a negative numeric argument. Similarly,
2198 @w{@kbd{C-x 4 .}} with a negative argument finds the previous tag
2199 location in another window.
2202 @findex pop-tag-mark
2203 @vindex find-tag-marker-ring-length
2204 As well as going back to places you've found tags recently, you can
2205 go back to places @emph{from where} you found them, using @kbd{M-*}
2206 (@code{pop-tag-mark}). Thus you can find and examine the definition
2207 of something with @kbd{M-.} and then return to where you were with
2210 Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
2211 a depth determined by the variable @code{find-tag-marker-ring-length}.
2213 @findex find-tag-regexp
2215 The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
2216 match a specified regular expression. It is just like @kbd{M-.} except
2217 that it does regexp matching instead of substring matching.
2220 @subsection Searching and Replacing with Tags Tables
2221 @cindex search and replace in multiple files
2222 @cindex multiple-file search and replace
2224 The commands in this section visit and search all the files listed
2225 in the selected tags table, one by one. For these commands, the tags
2226 table serves only to specify a sequence of files to search. These
2227 commands scan the list of tags tables starting with the first tags
2228 table (if any) that describes the current file, proceed from there to
2229 the end of the list, and then scan from the beginning of the list
2230 until they have covered all the tables in the list.
2233 @item M-x tags-search @key{RET} @var{regexp} @key{RET}
2234 Search for @var{regexp} through the files in the selected tags
2236 @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
2237 Perform a @code{query-replace-regexp} on each file in the selected tags table.
2239 Restart one of the commands above, from the current location of point
2240 (@code{tags-loop-continue}).
2244 @kbd{M-x tags-search} reads a regexp using the minibuffer, then
2245 searches for matches in all the files in the selected tags table, one
2246 file at a time. It displays the name of the file being searched so you
2247 can follow its progress. As soon as it finds an occurrence,
2248 @code{tags-search} returns.
2251 @findex tags-loop-continue
2252 Having found one match, you probably want to find all the rest.
2253 Type @kbd{M-,} (@code{tags-loop-continue}) to resume the
2254 @code{tags-search}, finding one more match. This searches the rest of
2255 the current buffer, followed by the remaining files of the tags table.
2257 @findex tags-query-replace
2258 @kbd{M-x tags-query-replace} performs a single
2259 @code{query-replace-regexp} through all the files in the tags table. It
2260 reads a regexp to search for and a string to replace with, just like
2261 ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
2262 tags-search}, but repeatedly, processing matches according to your
2263 input. @xref{Query Replace}, for more information on query replace.
2265 @vindex tags-case-fold-search
2266 @cindex case-sensitivity and tags search
2267 You can control the case-sensitivity of tags search commands by
2268 customizing the value of the variable @code{tags-case-fold-search}. The
2269 default is to use the same setting as the value of
2270 @code{case-fold-search} (@pxref{Search Case}).
2272 It is possible to get through all the files in the tags table with a
2273 single invocation of @kbd{M-x tags-query-replace}. But often it is
2274 useful to exit temporarily, which you can do with any input event that
2275 has no special query replace meaning. You can resume the query
2276 replace subsequently by typing @kbd{M-,}; this command resumes the
2277 last tags search or replace command that you did. For instance, to
2278 skip the rest of the current file, you can type @kbd{M-> M-,}.
2280 The commands in this section carry out much broader searches than the
2281 @code{find-tag} family. The @code{find-tag} commands search only for
2282 definitions of tags that match your substring or regexp. The commands
2283 @code{tags-search} and @code{tags-query-replace} find every occurrence
2284 of the regexp, as ordinary search commands and replace commands do in
2287 These commands create buffers only temporarily for the files that they
2288 have to search (those which are not already visited in Emacs buffers).
2289 Buffers in which no match is found are quickly killed; the others
2292 As an alternative to @code{tags-search}, you can run @command{grep}
2293 as a subprocess and have Emacs show you the matching lines one by one.
2294 @xref{Grep Searching}.
2297 @subsection Tags Table Inquiries
2302 Perform completion on the text around point, using the selected tags
2303 table if one is loaded (@code{completion-at-point}).
2304 @item M-x list-tags @key{RET} @var{file} @key{RET}
2305 Display a list of the tags defined in the program file @var{file}.
2306 @item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
2307 Display a list of all tags matching @var{regexp}.
2310 @cindex completion (symbol names)
2311 In most programming language modes, you can type @kbd{C-M-i} or
2312 @kbd{M-@key{TAB}} (@code{completion-at-point}) to complete the symbol
2313 at point. If there is a selected tags table, this command can use it
2314 to generate completion candidates. @xref{Symbol Completion}.
2317 @kbd{M-x list-tags} reads the name of one of the files covered by
2318 the selected tags table, and displays a list of tags defined in that
2319 file. Do not include a directory as part of the file name unless the
2320 file name recorded in the tags table includes a directory.
2322 @findex tags-apropos
2323 @vindex tags-apropos-verbose
2324 @vindex tags-tag-face
2325 @vindex tags-apropos-additional-actions
2326 @kbd{M-x tags-apropos} is like @code{apropos} for tags
2327 (@pxref{Apropos}). It displays a list of tags in the selected tags
2328 table whose entries match @var{regexp}. If the variable
2329 @code{tags-apropos-verbose} is non-@code{nil}, it displays the names
2330 of the tags files together with the tag names. You can customize the
2331 appearance of the output by setting the variable @code{tags-tag-face}
2332 to a face. You can display additional output by customizing the
2333 variable @code{tags-apropos-additional-actions}; see its documentation
2337 @kbd{M-x next-file} visits files covered by the selected tags table.
2338 The first time it is called, it visits the first file covered by the
2339 table. Each subsequent call visits the next covered file, unless a
2340 prefix argument is supplied, in which case it returns to the first
2344 @section Emacs Development Environment
2345 @cindex EDE (Emacs Development Environment)
2346 @cindex Emacs Development Environment
2347 @cindex Integrated development environment
2349 EDE (@dfn{Emacs Development Environment}) is a package that simplifies
2350 the task of creating, building, and debugging large programs with
2351 Emacs. It provides some of the features of an IDE, or @dfn{Integrated
2352 Development Environment}, in Emacs.
2354 This section provides a brief description of EDE usage.
2356 For full details, see @ref{Top, EDE,, ede, Emacs Development Environment}.
2359 For full details on Ede, type @kbd{C-h i} and then select the EDE
2363 EDE is implemented as a global minor mode (@pxref{Minor Modes}). To
2364 enable it, type @kbd{M-x global-ede-mode} or click on the
2365 @samp{Project Support (EDE)} item in the @samp{Tools} menu. You can
2366 also enable EDE each time you start Emacs, by adding the following
2367 line to your initialization file:
2374 Activating EDE adds a menu named @samp{Development} to the menu bar.
2375 Many EDE commands, including the ones described below, can be invoked
2378 EDE organizes files into @dfn{projects}, which correspond to
2379 directory trees. The @dfn{project root} is the topmost directory of a
2380 project. To define a new project, visit a file in the desired project
2381 root and type @kbd{M-x ede-new}. This command prompts for a
2382 @dfn{project type}, which refers to the underlying method that EDE
2383 will use to manage the project (@pxref{Creating a project, EDE,, ede,
2384 Emacs Development Environment}). The most common project types are
2385 @samp{Make}, which uses Makefiles, and @samp{Automake}, which uses GNU
2386 Automake (@pxref{Top, Automake,, automake, Automake}). In both cases,
2387 EDE also creates a file named @file{Project.ede}, which stores
2388 information about the project.
2390 A project may contain one or more @dfn{targets}. A target can be an
2391 object file, executable program, or some other type of file, which is
2392 ``built'' from one or more of the files in the project.
2394 To add a new @dfn{target} to a project, type @kbd{C-c . t}
2395 (@code{M-x ede-new-target}). This command also asks if you wish to
2396 ``add'' the current file to that target, which means that the target
2397 is to be built from that file. After you have defined a target, you
2398 can add more files to it by typing @kbd{C-c . a}
2399 (@code{ede-add-file}).
2401 To build a target, type @kbd{C-c . c} (@code{ede-compile-target}).
2402 To build all the targets in the project, type @kbd{C-c . C}
2403 (@code{ede-compile-project}). EDE uses the file types to guess how
2404 the target should be built.
2407 @include emerge-xtra.texi