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-2015 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 Emacs Lisp Regression Testing (ERT) 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}).
50 @findex vc-refresh-state
51 @findex vc-state-refresh
52 To update the VC state information for the file visited in the
53 current buffer, use the command @code{vc-refresh-state}. This command
54 is useful when you perform version control commands outside Emacs
55 (e.g., from the shell prompt), or if you put the buffer's file under a
56 different version control system, or remove it from version control
57 entirely. A companion command @code{vc-state-refresh} does the same,
58 but does not consider switching the version control system or removal
62 * Introduction to VC:: How version control works in general.
63 * VC Mode Line:: How the mode line shows version control status.
64 * Basic VC Editing:: How to edit a file under version control.
65 * Log Buffer:: Features available in log entry buffers.
66 * Registering:: Putting a file under version control.
67 * Old Revisions:: Examining and comparing old versions.
68 * VC Change Log:: Viewing the VC Change Log.
69 * VC Undo:: Canceling changes before or after committing.
70 * VC Ignore:: Ignore files under version control system.
71 * VC Directory Mode:: Listing files managed by version control.
72 * Branches:: Multiple lines of development.
74 * Miscellaneous VC:: Various other commands and features of VC.
75 * Customizing VC:: Variables that change VC's behavior.
79 @node Introduction to VC
80 @subsection Introduction to Version Control
82 VC allows you to use a version control system from within Emacs,
83 integrating the version control operations smoothly with editing. It
84 provides a uniform interface for common operations in many version
87 Some uncommon or intricate version control operations, such as
88 altering repository settings, are not supported in VC@. You should
89 perform such tasks outside Emacs, e.g., via the command line.
91 This section provides a general overview of version control, and
92 describes the version control systems that VC supports. You can skip
93 this section if you are already familiar with the version control system
97 * Why Version Control?:: Understanding the problems it addresses.
98 * Version Control Systems:: Supported version control back-end systems.
99 * VCS Concepts:: Words and concepts related to version control.
100 * VCS Merging:: How file conflicts are handled.
101 * VCS Changesets:: How changes are grouped.
102 * VCS Repositories:: Where version control repositories are stored.
103 * Types of Log File:: The VCS log in contrast to the ChangeLog.
106 @node Why Version Control?
107 @subsubsection Understanding the problems it addresses
109 Version control systems provide you with three important
114 @dfn{Reversibility}: the ability to back up to a previous state if you
115 discover that some modification you did was a mistake or a bad idea.
118 @dfn{Concurrency}: the ability to have many people modifying the same
119 collection of files knowing that conflicting modifications can be
120 detected and resolved.
123 @dfn{History}: the ability to attach historical data to your data,
124 such as explanatory comments about the intention behind each change to
125 it. Even for a programmer working solo, change histories are an
126 important aid to memory; for a multi-person project, they are a
127 vitally important form of communication among developers.
130 @node Version Control Systems
131 @subsubsection Supported Version Control Systems
133 @cindex back end (version control)
134 VC currently works with many different version control systems,
135 which it refers to as @dfn{back ends}:
141 SCCS was the first version control system ever built, and was long ago
142 superseded by more advanced ones. VC compensates for certain features
143 missing in SCCS (e.g., tag names for releases) by implementing them
144 itself. Other VC features, such as multiple branches, are simply
145 unavailable. Since SCCS is non-free, we recommend avoiding it.
149 CSSC is a free replacement for SCCS@. You should use CSSC only if, for
150 some reason, you cannot use a more recent and better-designed version
155 RCS is the free version control system around which VC was initially
156 built. It is relatively primitive: it cannot be used over the
157 network, and works at the level of individual files. Almost
158 everything you can do with RCS can be done through VC.
162 CVS is the free version control system that was, until recently (circa
163 2008), used by the majority of free software projects. Nowadays, it
164 is slowly being superseded by newer systems. CVS allows concurrent
165 multi-user development either locally or over the network. Unlike
166 newer systems, it lacks support for atomic commits and file
167 moving/renaming. VC supports all basic editing operations under CVS.
172 Subversion (svn) is a free version control system designed to be
173 similar to CVS but without its problems (e.g., it supports atomic
174 commits of filesets, and versioning of directories, symbolic links,
175 meta-data, renames, copies, and deletes).
179 Git is a decentralized version control system originally invented by
180 Linus Torvalds to support development of Linux (his kernel). VC
181 supports many common Git operations, but others, such as repository
182 syncing, must be done from the command line.
187 Mercurial (hg) is a decentralized version control system broadly
188 resembling Git. VC supports most Mercurial commands, with the
189 exception of repository sync operations.
194 Bazaar (bzr) is a decentralized version control system that supports
195 both repository-based and decentralized versioning. VC supports most
196 basic editing operations under Bazaar.
201 SRC (src) is RCS, reloaded - a specialized version-control system
202 designed for single-file projects worked on by only one person. It
203 allows multiple files with independent version-control histories to
204 exist in one directory, and is thus particularly well suited for
205 maintaining small documents, scripts, and dotfiles. While it uses RCS
206 for revision storage, it presents a modern user interface featuring
207 lockless operation and integer sequential version numbers. VC
208 supports almost all SRC operations.
212 @subsubsection Concepts of Version Control
215 @cindex registered file
216 When a file is under version control, we say that it is
217 @dfn{registered} in the version control system. The system has a
218 @dfn{repository} which stores both the file's present state and its
219 change history---enough to reconstruct the current version or any
220 earlier version. The repository also contains other information, such
221 as @dfn{log entries} that describe the changes made to each file.
224 @cindex checking out files
225 The copy of a version-controlled file that you actually edit is
226 called the @dfn{work file}. You can change each work file as you
227 would an ordinary file. After you are done with a set of changes, you
228 may @dfn{commit} (or @dfn{check in}) the changes; this records the
229 changes in the repository, along with a descriptive log entry.
232 A directory tree of work files is called a @dfn{working tree}.
236 Each commit creates a new @dfn{revision} in the repository. The
237 version control system keeps track of all past revisions and the
238 changes that were made in each revision. Each revision is named by a
239 @dfn{revision ID}, whose format depends on the version control system;
240 in the simplest case, it is just an integer.
242 To go beyond these basic concepts, you will need to understand three
243 aspects in which version control systems differ. As explained in the
244 next three sections, they can be lock-based or merge-based; file-based
245 or changeset-based; and centralized or decentralized. VC handles all
246 these modes of operation, but it cannot hide the differences.
249 @subsubsection Merge-based vs lock-based Version Control
251 A version control system typically has some mechanism to coordinate
252 between users who want to change the same file. There are two ways to
253 do this: merging and locking.
255 @cindex merging-based version
256 In a version control system that uses merging, each user may modify
257 a work file at any time. The system lets you @dfn{merge} your work
258 file, which may contain changes that have not been committed, with the
259 latest changes that others have committed.
261 @cindex locking-based version
262 Older version control systems use a @dfn{locking} scheme instead.
263 Here, work files are normally read-only. To edit a file, you ask the
264 version control system to make it writable for you by @dfn{locking}
265 it; only one user can lock a given file at any given time. This
266 procedure is analogous to, but different from, the locking that Emacs
267 uses to detect simultaneous editing of ordinary files
268 (@pxref{Interlocking}). When you commit your changes, that unlocks
269 the file, and the work file becomes read-only again. Other users may
270 then lock the file to make their own changes.
272 Both locking and merging systems can have problems when multiple
273 users try to modify the same file at the same time. Locking systems
274 have @dfn{lock conflicts}; a user may try to check a file out and be
275 unable to because it is locked. In merging systems, @dfn{merge
276 conflicts} happen when you commit a change to a file that conflicts
277 with a change committed by someone else after your checkout. Both
278 kinds of conflict have to be resolved by human judgment and
279 communication. Experience has shown that merging is superior to
280 locking, both in convenience to developers and in minimizing the
281 number and severity of conflicts that actually occur.
283 SCCS always uses locking. RCS is lock-based by default but can be
284 told to operate in a merging style. CVS and Subversion are
285 merge-based by default but can be told to operate in a locking mode.
286 Decentralized version control systems, such as Git and Mercurial, are
287 exclusively merging-based.
289 VC mode supports both locking and merging version control. The
290 terms ``commit'' and ``update'' are used in newer version control
291 systems; older lock-based systems use the terms ``check in'' and
292 ``check out''. VC hides the differences between them as much as
296 @subsubsection Changeset-based vs File-based Version Control
298 @cindex file-based version control
299 On SCCS, RCS, CVS, and other early version control systems, version
300 control operations are @dfn{file-based}: each file has its own comment
301 and revision history separate from that of all other files. Newer
302 systems, beginning with Subversion, are @dfn{changeset-based}: a
303 commit may include changes to several files, and the entire set of
304 changes is handled as a unit. Any comment associated with the change
305 does not belong to a single file, but to the changeset itself.
307 @cindex changeset-based version control
308 Changeset-based version control is more flexible and powerful than
309 file-based version control; usually, when a change to multiple files
310 has to be reversed, it's good to be able to easily identify and remove
313 @node VCS Repositories
314 @subsubsection Decentralized vs Centralized Repositories
316 @cindex centralized version control
317 @cindex decentralized version control
318 @cindex distributed version control
319 Early version control systems were designed around a
320 @dfn{centralized} model in which each project has only one repository
321 used by all developers. SCCS, RCS, CVS, and Subversion share this
322 kind of model. One of its drawbacks is that the repository is a choke
323 point for reliability and efficiency.
325 GNU Arch pioneered the concept of @dfn{distributed} or
326 @dfn{decentralized} version control, later implemented in Git,
327 Mercurial, and Bazaar. A project may have several different
328 repositories, and these systems support a sort of super-merge between
329 repositories that tries to reconcile their change histories. In
330 effect, there is one repository for each developer, and repository
331 merges take the place of commit operations.
333 VC helps you manage the traffic between your personal workfiles and
334 a repository. Whether the repository is a single master, or one of a
335 network of peer repositories, is not something VC has to care about.
337 @node Types of Log File
338 @subsubsection Types of Log File
339 @cindex types of log file
340 @cindex log File, types of
341 @cindex version control log
343 Projects that use a version control system can have two types of log
344 for changes. One is the log maintained by the version control system:
345 each time you commit a change, you fill out a @dfn{log entry} for the
346 change (@pxref{Log Buffer}). This is called the @dfn{version control
349 The other kind of log is the file @file{ChangeLog} (@pxref{Change
350 Log}). It provides a chronological record of all changes to a large
351 portion of a program---typically one directory and its subdirectories.
352 A small program would use one @file{ChangeLog} file; a large program
353 may have a @file{ChangeLog} file in each major directory.
354 @xref{Change Log}. Programmers have used change logs since long
355 before version control systems.
357 Changeset-based version systems typically maintain a changeset-based
358 modification log for the entire system, which makes change log files
359 somewhat redundant. One advantage that they retain is that it is
360 sometimes useful to be able to view the transaction history of a
361 single directory separately from those of other directories. Another
362 advantage is that commit logs can't be fixed in many version control
365 A project maintained with version control can use just the version
366 control log, or it can use both kinds of logs. It can handle some
367 files one way and some files the other way. Each project has its
368 policy, which you should follow.
370 When the policy is to use both, you typically want to write an entry
371 for each change just once, then put it into both logs. You can write
372 the entry in @file{ChangeLog}, then copy it to the log buffer with
373 @kbd{C-c C-a} when committing the change (@pxref{Log Buffer}). Or you
374 can write the entry in the log buffer while committing the change, and
375 later use the @kbd{C-x v a} command to copy it to @file{ChangeLog}
377 (@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
380 (@pxref{Change Logs and VC}).
384 @subsection Version Control and the Mode Line
385 @cindex VC mode line indicator
387 When you visit a file that is under version control, Emacs indicates
388 this on the mode line. For example, @samp{Bzr-1223} says that Bazaar
389 is used for that file, and the current revision ID is 1223.
391 @cindex version control status
392 The character between the back-end name and the revision ID
393 indicates the @dfn{version control status} of the work file. In a
394 merge-based version control system, a @samp{-} character indicates
395 that the work file is unmodified, and @samp{:} indicates that it has
396 been modified. @samp{!} indicates that the file contains conflicts as
397 result of a recent merge operation (@pxref{Merging}), or that the file
398 was removed from the version control. Finally, @samp{?} means that
399 the file is under version control, but is missing from the working
402 In a lock-based system, @samp{-} indicates an unlocked file, and
403 @samp{:} a locked file; if the file is locked by another user (for
404 instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
405 @samp{@@} means that the file was locally added, but not yet committed
406 to the master repository.
408 On a graphical display, you can move the mouse over this mode line
409 indicator to pop up a tool-tip, which displays a more verbose
410 description of the version control status. Pressing @kbd{Mouse-1}
411 over the indicator pops up a menu of VC commands, identical to
412 @samp{Tools / Version Control} on the menu bar.
414 @vindex auto-revert-check-vc-info
415 When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is
416 under version control, it updates the version control information in
417 the mode line. However, Auto Revert mode may not properly update this
418 information if the version control status changes without changes to
419 the work file, from outside the current Emacs session. If you set
420 @code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates
421 the version control status information every
422 @code{auto-revert-interval} seconds, even if the work file itself is
423 unchanged. The resulting CPU usage depends on the version control
424 system, but is usually not excessive.
426 @node Basic VC Editing
427 @subsection Basic Editing under Version Control
431 Most VC commands operate on @dfn{VC filesets}. A VC fileset is a
432 collection of one or more files that a VC operation acts on. When you
433 type VC commands in a buffer visiting a version-controlled file, the
434 VC fileset is simply that one file. When you type them in a VC
435 Directory buffer, and some files in it are marked, the VC fileset
436 consists of the marked files (@pxref{VC Directory Mode}).
438 On modern changeset-based version control systems (@pxref{VCS
439 Changesets}), VC commands handle multi-file VC filesets as a group.
440 For example, committing a multi-file VC fileset generates a single
441 revision, containing the changes to all those files. On older
442 file-based version control systems like CVS, each file in a multi-file
443 VC fileset is handled individually; for example, a commit generates
444 one revision for each changed file.
448 Perform the next appropriate version control operation on the current
452 @findex vc-next-action
454 The principal VC command is a multi-purpose command, @kbd{C-x v v}
455 (@code{vc-next-action}), which performs the most appropriate
456 action on the current VC fileset: either registering it with a version
457 control system, or committing it, or unlocking it, or merging changes
458 into it. The precise actions are described in detail in the following
459 subsections. You can use @kbd{C-x v v} either in a file-visiting
460 buffer or in a VC Directory buffer.
462 Note that VC filesets are distinct from the named filesets used
463 for viewing and visiting files in functional groups
464 (@pxref{Filesets}). Unlike named filesets, VC filesets are not named
465 and don't persist across sessions.
468 * VC With A Merging VCS:: Without locking: default mode for CVS.
469 * VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS.
470 * Advanced C-x v v:: Advanced features available with a prefix argument.
473 @node VC With A Merging VCS
474 @subsubsection Basic Version Control with Merging
476 On a merging-based version control system (i.e., most modern ones;
477 @pxref{VCS Merging}), @kbd{C-x v v} does the following:
481 If there is more than one file in the VC fileset and the files have
482 inconsistent version control statuses, signal an error. (Note,
483 however, that a fileset is allowed to include both newly-added
484 files and modified files; @pxref{Registering}.)
487 If none of the files in the VC fileset are registered with a version
488 control system, register the VC fileset, i.e., place it under version
489 control. @xref{Registering}. If Emacs cannot find a system to
490 register under, it prompts for a repository type, creates a new
491 repository, and registers the VC fileset with it.
494 If every work file in the VC fileset is unchanged, do nothing.
497 If every work file in the VC fileset has been modified, commit the
498 changes. To do this, Emacs pops up a @file{*vc-log*} buffer; type the
499 desired log entry for the new revision, followed by @kbd{C-c C-c} to
500 commit. @xref{Log Buffer}.
502 If committing to a shared repository, the commit may fail if the
503 repository that has been changed since your last update. In that
504 case, you must perform an update before trying again. On a
505 decentralized version control system, use @kbd{C-x v +}
506 (@pxref{Pulling / Pushing}) or @kbd{C-x v m} (@pxref{Merging}).
507 On a centralized version control system, type @kbd{C-x v v} again to
508 merge in the repository changes.
511 Finally, if you are using a centralized version control system, check
512 if each work file in the VC fileset is up-to-date. If any file has
513 been changed in the repository, offer to update it.
516 These rules also apply when you use RCS in its non-locking mode,
517 except that changes are not automatically merged from the repository.
518 Nothing informs you if another user has committed changes in the same
519 file since you began editing it; when you commit your revision, his
520 changes are removed (however, they remain in the repository and are
521 thus not irrevocably lost). Therefore, you must verify that the
522 current revision is unchanged before committing your changes. In
523 addition, locking is possible with RCS even in this mode: @kbd{C-x v
524 v} with an unmodified file locks the file, just as it does with RCS in
525 its normal locking mode (@pxref{VC With A Locking VCS}).
527 @node VC With A Locking VCS
528 @subsubsection Basic Version Control with Locking
530 On a locking-based version control system (such as SCCS, and RCS in
531 its default mode), @kbd{C-x v v} does the following:
535 If there is more than one file in the VC fileset and the files have
536 inconsistent version control statuses, signal an error.
539 If each file in the VC fileset is not registered with a version
540 control system, register the VC fileset. @xref{Registering}. If
541 Emacs cannot find a system to register under, it prompts for a
542 repository type, creates a new repository, and registers the VC
546 If each file is registered and unlocked, lock it and make it writable,
547 so that you can begin to edit it.
550 If each file is locked by you and contains changes, commit the
551 changes. To do this, Emacs pops up a @file{*vc-log*} buffer; type the
552 desired log entry for the new revision, followed by @kbd{C-c C-c} to
553 commit (@pxref{Log Buffer}).
556 If each file is locked by you, but you have not changed it, release
557 the lock and make the file read-only again.
560 If each file is locked by another user, ask whether you want to
561 steal the lock. If you say yes, the file becomes locked by you,
562 and a warning message is sent to the user who had formerly locked the
566 These rules also apply when you use CVS in locking mode, except
567 that CVS does not support stealing locks.
569 @node Advanced C-x v v
570 @subsubsection Advanced Control in @kbd{C-x v v}
572 @cindex revision ID in version control
573 When you give a prefix argument to @code{vc-next-action} (@kbd{C-u
574 C-x v v}), it still performs the next logical version control
575 operation, but accepts additional arguments to specify precisely how
580 @cindex specific version control system
581 You can specify the name of a version control system. This is useful
582 if the fileset can be managed by more than one version control system,
583 and Emacs fails to detect the correct one.
586 Otherwise, if using CVS or RCS, you can specify a revision ID.
588 If the fileset is modified (or locked), this makes Emacs commit with
589 that revision ID@. You can create a new branch by supplying an
590 appropriate revision ID (@pxref{Branches}).
592 If the fileset is unmodified (and unlocked), this checks the specified
593 revision into the working tree. You can also specify a revision on
594 another branch by giving its revision or branch ID (@pxref{Switching
595 Branches}). An empty argument (i.e., @kbd{C-u C-x v v @key{RET}})
596 checks out the latest (head) revision on the current branch.
598 This is silently ignored on a decentralized version control system.
599 Those systems do not let you specify your own revision IDs, nor do
600 they use the concept of checking out individual files.
604 @subsection Features of the Log Entry Buffer
606 @cindex C-c C-c @r{(Log Edit mode)}
607 @findex log-edit-done
608 When you tell VC to commit a change, it pops up a buffer named
609 @file{*vc-log*}. In this buffer, you should write a @dfn{log entry}
610 describing the changes you have made (@pxref{Why Version Control?}).
611 After you are done, type @kbd{C-c C-c} (@code{log-edit-done}) to exit
612 the buffer and commit the change, together with your log entry.
614 @cindex Log Edit mode
615 @cindex mode, Log Edit
616 @vindex vc-log-mode-hook
617 @c FIXME: Mention log-edit-mode-hook here? --xfq
618 The major mode for the @file{*vc-log*} buffer is Log Edit mode, a
619 variant of Text mode (@pxref{Text Mode}). On entering Log Edit mode,
620 Emacs runs the hooks @code{text-mode-hook} and @code{vc-log-mode-hook}
623 In the @file{*vc-log*} buffer, you can write one or more @dfn{header
624 lines}, specifying additional information to be supplied to the
625 version control system. Each header line must occupy a single line at
626 the top of the buffer; the first line that is not a header line is
627 treated as the start of the log entry. For example, the following
628 header line states that the present change was not written by you, but
629 by another developer:
632 Author: J. R. Hacker <jrh@@example.com>
636 Apart from the @samp{Author} header, Emacs recognizes the headers
637 @samp{Date} (a manually-specified commit time) and @samp{Fixes} (a
638 reference to a bug fixed by the change). Not all version control
639 systems recognize all headers: Bazaar recognizes all three headers,
640 while Git, Mercurial, and Monotone recognize only @samp{Author} and
641 @samp{Date}. If you specify a header for a system that does not
642 support it, the header is treated as part of the log entry.
644 @kindex C-c C-f @r{(Log Edit mode)}
645 @findex log-edit-show-files
646 @kindex C-c C-d @r{(Log Edit mode)}
647 @findex log-edit-show-diff
648 While in the @file{*vc-log*} buffer, the current VC fileset is
649 considered to be the fileset that will be committed if you type
650 @w{@kbd{C-c C-c}}. To view a list of the files in the VC fileset,
651 type @w{@kbd{C-c C-f}} (@code{log-edit-show-files}). To view a diff
652 of changes between the VC fileset and the version from which you
653 started editing (@pxref{Old Revisions}), type @kbd{C-c C-d}
654 (@code{log-edit-show-diff}).
656 @kindex C-c C-a @r{(Log Edit mode)}
657 @findex log-edit-insert-changelog
658 If the VC fileset includes one or more @file{ChangeLog} files
659 (@pxref{Change Log}), type @kbd{C-c C-a}
660 (@code{log-edit-insert-changelog}) to pull the relevant entries into
661 the @file{*vc-log*} buffer. If the topmost item in each
662 @file{ChangeLog} was made under your user name on the current date,
663 this command searches that item for entries matching the file(s) to be
664 committed, and inserts them.
666 If you are using CVS or RCS, see @ref{Change Logs and VC}, for the
667 opposite way of working---generating ChangeLog entries from the Log
671 To abort a commit, just @emph{don't} type @kbd{C-c C-c} in that
672 buffer. You can switch buffers and do other editing. As long as you
673 don't try to make another commit, the entry you were editing remains
674 in the @file{*vc-log*} buffer, and you can go back to that buffer at
675 any time to complete the commit.
677 @kindex M-n @r{(Log Edit mode)}
678 @kindex M-p @r{(Log Edit mode)}
679 @kindex M-s @r{(Log Edit mode)}
680 @kindex M-r @r{(Log Edit mode)}
681 You can also browse the history of previous log entries to duplicate
682 a commit comment. This can be useful when you want to make several
683 commits with similar comments. The commands @kbd{M-n}, @kbd{M-p},
684 @kbd{M-s} and @kbd{M-r} for doing this work just like the minibuffer
685 history commands (@pxref{Minibuffer History}), except that they are
686 used outside the minibuffer.
689 @subsection Registering a File for Version Control
693 Register the visited file for version control.
698 The command @kbd{C-x v i} (@code{vc-register}) @dfn{registers} each
699 file in the current VC fileset, placing it under version control.
700 This is essentially equivalent to the action of @kbd{C-x v v} on an
701 unregistered VC fileset (@pxref{Basic VC Editing}), except that if the
702 VC fileset is already registered, @kbd{C-x v i} signals an error
703 whereas @kbd{C-x v v} performs some other action.
705 To register a file, Emacs must choose a version control system. For
706 a multi-file VC fileset, the VC Directory buffer specifies the system
707 to use (@pxref{VC Directory Mode}). For a single-file VC fileset, if
708 the file's directory already contains files registered in a version
709 control system, or if the directory is part of a directory tree
710 controlled by a version control system, Emacs chooses that system. In
711 the event that more than one version control system is applicable,
712 Emacs uses the one that appears first in the variable
714 @code{vc-handled-backends}.
717 @code{vc-handled-backends} (@pxref{Customizing VC}).
719 If Emacs cannot find a version control system to register the file
720 under, it prompts for a repository type, creates a new repository, and
721 registers the file into that repository.
723 On most version control systems, registering a file with @kbd{C-x v
724 i} or @kbd{C-x v v} adds it to the working tree but not to the
725 repository. Such files are labeled as @samp{added} in the VC
726 Directory buffer, and show a revision ID of @samp{@@@@} in the mode
727 line. To make the registration take effect in the repository, you
728 must perform a commit (@pxref{Basic VC Editing}). Note that a single
729 commit can include both file additions and edits to existing files.
731 On a locking-based version control system (@pxref{VCS Merging}),
732 registering a file leaves it unlocked and read-only. Type @kbd{C-x v
733 v} to start editing it.
736 @subsection Examining And Comparing Old Revisions
740 Compare the work files in the current VC fileset with the versions you
741 started from (@code{vc-diff}). With a prefix argument, prompt for two
742 revisions of the current VC fileset and compare them. You can also
743 call this command from a Dired buffer (@pxref{Dired}).
747 Like @kbd{C-x v =}, but using Ediff. @xref{Top,, Ediff, ediff, The
752 Compare the entire working tree to the revision you started from
753 (@code{vc-root-diff}). With a prefix argument, prompt for two
754 revisions and compare their trees.
757 Prompt for a revision of the current file, and visit it in a separate
758 buffer (@code{vc-revision-other-window}).
761 Display an annotated version of the current file: for each line, show
762 the latest revision in which it was modified (@code{vc-annotate}).
767 @kbd{C-x v =} (@code{vc-diff}) displays a @dfn{diff} which compares
768 each work file in the current VC fileset to the version(s) from which
769 you started editing. The diff is displayed in another window, in a
770 Diff mode buffer (@pxref{Diff Mode}) named @file{*vc-diff*}. The
771 usual Diff mode commands are available in this buffer. In particular,
772 the @kbd{g} (@code{revert-buffer}) command performs the file
773 comparison again, generating a new diff.
776 To compare two arbitrary revisions of the current VC fileset, call
777 @code{vc-diff} with a prefix argument: @kbd{C-u C-x v =}. This
778 prompts for two revision IDs (@pxref{VCS Concepts}), and displays a
779 diff between those versions of the fileset. This will not work
780 reliably for multi-file VC filesets, if the version control system is
781 file-based rather than changeset-based (e.g., CVS), since then
782 revision IDs for different files would not be related in any
785 Instead of the revision ID, some version control systems let you
786 specify revisions in other formats. For instance, under Bazaar you
787 can enter @samp{date:yesterday} for the argument to @kbd{C-u C-x v =}
788 (and related commands) to specify the first revision committed after
789 yesterday. See the documentation of the version control system for
792 If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a Dired buffer
793 (@pxref{Dired}), the file listed on the current line is treated as the
798 @kbd{M-x vc-ediff} works like @kbd{C-x v =}, except that it uses an
799 Ediff session. @xref{Top,, Ediff, ediff, The Ediff Manual}.
804 @kbd{C-x v D} (@code{vc-root-diff}) is similar to @kbd{C-x v =}, but
805 it displays the changes in the entire current working tree (i.e., the
806 working tree containing the current VC fileset). If you invoke this
807 command from a Dired buffer, it applies to the working tree containing
810 @vindex vc-diff-switches
811 You can customize the @command{diff} options that @kbd{C-x v =} and
812 @kbd{C-x v D} use for generating diffs. The options used are taken
813 from the first non-@code{nil} value amongst the variables
814 @code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches}, and
815 @code{diff-switches} (@pxref{Comparing Files}), in that order. Here,
816 @var{backend} stands for the relevant version control system,
817 e.g., @code{bzr} for Bazaar. Since @code{nil} means to check the
818 next variable in the sequence, either of the first two may use the
819 value @code{t} to mean no switches at all. Most of the
820 @code{vc-@var{backend}-diff-switches} variables default to @code{nil},
821 but some default to @code{t}; these are for version control systems
822 whose @code{diff} implementations do not accept common diff options,
825 @findex vc-revision-other-window
827 To directly examine an older version of a file, visit the work file
828 and type @kbd{C-x v ~ @var{revision} @key{RET}}
829 (@code{vc-revision-other-window}). This retrieves the file version
830 corresponding to @var{revision}, saves it to
831 @file{@var{filename}.~@var{revision}~}, and visits it in a separate
835 @vindex vc-annotate-background-mode
837 Many version control systems allow you to view files @dfn{annotated}
838 with per-line revision information, by typing @kbd{C-x v g}
839 (@code{vc-annotate}). This creates a new ``annotate'' buffer
840 displaying the file's text, with each line colored to show how old it
841 is. Red text is new, blue is old, and intermediate colors indicate
842 intermediate ages. By default, the color is scaled over the full
843 range of ages, such that the oldest changes are blue, and the newest
844 changes are red. If the variable @code{vc-annotate-background-mode}
845 is non-@code{nil}, the colors expressing the age of each line are
846 applied to the background color, leaving the foreground at its default
849 When you give a prefix argument to this command, Emacs reads two
850 arguments using the minibuffer: the revision to display and annotate
851 (instead of the current file contents), and the time span in days the
852 color range should cover.
854 From the ``annotate'' buffer, these and other color scaling options are
855 available from the @samp{VC-Annotate} menu. In this buffer, you can
856 also use the following keys to browse the annotations of past revisions,
857 view diffs, or view log entries:
861 Annotate the previous revision, i.e., the revision before the one
862 currently annotated. A numeric prefix argument is a repeat count, so
863 @kbd{C-u 10 p} would take you back 10 revisions.
866 Annotate the next revision, i.e., the revision after the one
867 currently annotated. A numeric prefix argument is a repeat count.
870 Annotate the revision indicated by the current line.
873 Annotate the revision before the one indicated by the current line.
874 This is useful to see the state the file was in before the change on
875 the current line was made.
878 Show in a buffer the file revision indicated by the current line.
881 Display the diff between the current line's revision and the previous
882 revision. This is useful to see what the current line's revision
883 actually changed in the file.
886 Display the diff between the current line's revision and the previous
887 revision for all files in the changeset (for VC systems that support
888 changesets). This is useful to see what the current line's revision
889 actually changed in the tree.
892 Show the log of the current line's revision. This is useful to see
893 the author's description of the changes in the revision on the current
897 Annotate the working revision--the one you are editing. If you used
898 @kbd{p} and @kbd{n} to browse to other revisions, use this key to
899 return to your working revision.
902 Toggle the annotation visibility. This is useful for looking just at
903 the file contents without distraction from the annotations.
907 @subsection VC Change Log
911 Display the change history for the current fileset
912 (@code{vc-print-log}).
915 Display the change history for the current repository
916 (@code{vc-print-root-log}).
919 Display the changes that a ``pull'' operation will retrieve
920 (@code{vc-log-incoming}).
923 Display the changes that will be sent by the next ``push'' operation
924 (@code{vc-log-outgoing}).
929 @kbd{C-x v l} (@code{vc-print-log}) displays a buffer named
930 @file{*vc-change-log*}, showing the history of changes made to the
931 current file, including who made the changes, the dates, and the log
932 entry for each change (these are the same log entries you would enter
933 via the @file{*vc-log*} buffer; @pxref{Log Buffer}). Point is
934 centered at the revision of the file currently being visited. With a
935 prefix argument, the command prompts for the revision to center on,
936 and the maximum number of revisions to display.
938 If you call @kbd{C-x v l} from a VC Directory buffer (@pxref{VC
939 Directory Mode}) or a Dired buffer (@pxref{Dired}), it applies to the
940 file listed on the current line.
942 @findex vc-print-root-log
943 @findex log-view-toggle-entry-display
944 @kbd{C-x v L} (@code{vc-print-root-log}) displays a
945 @file{*vc-change-log*} buffer showing the history of the entire
946 version-controlled directory tree (RCS, SCCS, and CVS do not support
947 this feature). With a prefix argument, the command prompts for the
948 maximum number of revisions to display.
950 The @kbd{C-x v L} history is shown in a compact form, usually
951 showing only the first line of each log entry. However, you can type
952 @key{RET} (@code{log-view-toggle-entry-display}) in the
953 @file{*vc-change-log*} buffer to reveal the entire log entry for the
954 revision at point. A second @key{RET} hides it again.
956 On a decentralized version control system, the @kbd{C-x v I}
957 (@code{vc-log-incoming}) command displays a log buffer showing the
958 changes that will be applied, the next time you run the version
959 control system's pull command to get new revisions from another
960 repository (@pxref{Pulling / Pushing}). This other repository is the default
961 one from which changes are pulled, as defined by the version control
962 system; with a prefix argument, @code{vc-log-incoming} prompts for a
963 specific repository. Similarly, @kbd{C-x v O}
964 (@code{vc-log-outgoing}) shows the changes that will be sent to
965 another repository, the next time you run the push command; with a
966 prefix argument, it prompts for a specific destination repository.
968 In the @file{*vc-change-log*} buffer, you can use the following keys
969 to move between the logs of revisions and of files, and to examine and
970 compare past revisions (@pxref{Old Revisions}):
974 Move to the previous revision entry. (Revision entries in the log
975 buffer are usually in reverse-chronological order, so the previous
976 revision-item usually corresponds to a newer revision.) A numeric
977 prefix argument is a repeat count.
980 Move to the next revision entry. A numeric prefix argument is a
984 Move to the log of the previous file, if showing logs for a multi-file
985 VC fileset. Otherwise, just move to the beginning of the log. A
986 numeric prefix argument is a repeat count.
989 Move to the log of the next file, if showing logs for a multi-file VC
990 fileset. A numeric prefix argument is a repeat count.
993 Annotate the revision on the current line (@pxref{Old Revisions}).
996 Modify the change comment displayed at point. Note that not all VC
997 systems support modifying change comments.
1000 Visit the revision indicated at the current line.
1003 Display a diff between the revision at point and the next earlier
1004 revision, for the specific file.
1007 Display the changeset diff between the revision at point and the next
1008 earlier revision. This shows the changes to all files made in that
1012 In a compact-style log buffer (e.g., the one created by @kbd{C-x v
1013 L}), toggle between showing and hiding the full log entry for the
1017 @vindex vc-log-show-limit
1018 Because fetching many log entries can be slow, the
1019 @file{*vc-change-log*} buffer displays no more than 2000 revisions by
1020 default. The variable @code{vc-log-show-limit} specifies this limit;
1021 if you set the value to zero, that removes the limit. You can also
1022 increase the number of revisions shown in an existing
1023 @file{*vc-change-log*} buffer by clicking on the @samp{Show 2X
1024 entries} or @samp{Show unlimited entries} buttons at the end of the
1025 buffer. However, RCS, SCCS, and CVS do not support this feature.
1027 @findex vc-region-history
1028 A useful variant of examining changes is provided by the command
1029 @kbd{vc-region-history}, which shows a @file{*VC-history*} buffer with
1030 the history of changes to the region of the current file between point
1031 and the mark (@pxref{Mark}). The history of changes includes the
1032 commit log messages and also the changes themselves in the Diff
1035 Invoke this command after marking the region of the current file in
1036 whose changes you are interested. In the @file{*VC-history*} buffer
1037 it pops up, you can use all of the commands available in the
1038 @file{*vc-change-log*} buffer described above, and also the commands
1039 defined by Diff mode (@pxref{Diff Mode}).
1041 This command is currently available only with Git.
1044 @subsection Undoing Version Control Actions
1048 Revert the work file(s) in the current VC fileset to the last revision
1054 @vindex vc-revert-show-diff
1055 If you want to discard all the changes you have made to the current
1056 VC fileset, type @kbd{C-x v u} (@code{vc-revert-buffer}). This shows
1057 you a diff between the work file(s) and the revision from which you
1058 started editing, and asks for confirmation for discarding the changes.
1059 If you agree, the fileset is reverted. If you don't want @kbd{C-x v
1060 u} to show a diff, set the variable @code{vc-revert-show-diff} to
1061 @code{nil} (you can still view the diff directly with @kbd{C-x v =};
1062 @pxref{Old Revisions}). Note that @kbd{C-x v u} cannot be reversed
1063 with the usual undo commands (@pxref{Undo}), so use it with care.
1065 On locking-based version control systems, @kbd{C-x v u} leaves files
1066 unlocked; you must lock again to resume editing. You can also use
1067 @kbd{C-x v u} to unlock a file if you lock it and then decide not to
1071 @subsection Ignore Version Control Files
1075 Ignore a file under current version control system. (@code{vc-ignore}).
1080 Many source trees contain some files that do not need to be
1081 versioned, such as editor backups, object or bytecode files, and built
1082 programs. You can simply not add them, but then they'll always crop
1083 up as unknown files. You can also tell the version control system to
1084 ignore these files by adding them to the ignore file at the top of the
1085 tree. @kbd{C-x v G} (@code{vc-ignore}) can help you do this. When
1086 called with a prefix argument, you can remove a file from the ignored
1089 @node VC Directory Mode
1090 @subsection VC Directory Mode
1092 @cindex VC Directory buffer
1093 The @dfn{VC Directory buffer} is a specialized buffer for viewing
1094 the version control statuses of the files in a directory tree, and
1095 performing version control operations on those files. In particular,
1096 it is used to specify multi-file VC filesets for commands like
1097 @w{@kbd{C-x v v}} to act on (@pxref{VC Directory Commands}).
1101 To use the VC Directory buffer, type @kbd{C-x v d} (@code{vc-dir}).
1102 This reads a directory name using the minibuffer, and switches to a VC
1103 Directory buffer for that directory. By default, the buffer is named
1104 @file{*vc-dir*}. Its contents are described
1109 in @ref{VC Directory Buffer}.
1112 The @code{vc-dir} command automatically detects the version control
1113 system to be used in the specified directory. In the event that more
1114 than one system is being used in the directory, you should invoke the
1115 command with a prefix argument, @kbd{C-u C-x v d}; this prompts for
1116 the version control system which the VC Directory buffer should use.
1121 @cindex CVS directory mode
1122 In addition to the VC Directory buffer, Emacs has a similar facility
1123 called PCL-CVS which is specialized for CVS@. @xref{Top, , About
1124 PCL-CVS, pcl-cvs, PCL-CVS---The Emacs Front-End to CVS}.
1128 * Buffer: VC Directory Buffer. What the buffer looks like and means.
1129 * Commands: VC Directory Commands. Commands to use in a VC directory buffer.
1132 @node VC Directory Buffer
1133 @subsubsection The VC Directory Buffer
1135 The VC Directory buffer contains a list of version-controlled files
1136 and their version control statuses. It lists files in the current
1137 directory (the one specified when you called @kbd{C-x v d}) and its
1138 subdirectories, but only those with a noteworthy status. Files
1139 that are up-to-date (i.e., the same as in the repository) are
1140 omitted. If all the files in a subdirectory are up-to-date, the
1141 subdirectory is not listed either. As an exception, if a file has
1142 become up-to-date as a direct result of a VC command, it is listed.
1144 Here is an example of a VC Directory buffer listing:
1151 unregistered temp.txt
1158 Two work files have been modified but not committed:
1159 @file{configure.ac} in the current directory, and @file{foo.c} in the
1160 @file{src/} subdirectory. The file named @file{README} has been added
1161 but is not yet committed, while @file{temp.txt} is not under version
1162 control (@pxref{Registering}).
1164 The @samp{*} characters next to the entries for @file{README} and
1165 @file{src/main.c} indicate that the user has marked out these files as
1166 the current VC fileset
1171 (@pxref{VC Directory Commands}).
1174 The above example is typical for a decentralized version control
1175 system like Bazaar, Git, or Mercurial. Other systems can show other
1176 statuses. For instance, CVS shows the @samp{needs-update} status if
1177 the repository has changes that have not been applied to the work
1178 file. RCS and SCCS show the name of the user locking a file as its
1182 @vindex vc-stay-local
1183 @vindex vc-cvs-stay-local
1184 On CVS and Subversion, the @code{vc-dir} command normally contacts
1185 the repository, which may be on a remote machine, to check for
1186 updates. If you change the variable @code{vc-stay-local} or
1187 @code{vc-cvs-stay-local} (for CVS) to @code{nil} (@pxref{CVS
1188 Options}), then Emacs avoids contacting a remote repository when
1189 generating the VC Directory buffer (it will still contact it when
1190 necessary, e.g., when doing a commit). This may be desirable if you
1191 are working offline or the network is slow.
1194 @vindex vc-directory-exclusion-list
1195 The VC Directory buffer omits subdirectories listed in the variable
1196 @code{vc-directory-exclusion-list}. Its default value contains
1197 directories that are used internally by version control systems.
1199 @node VC Directory Commands
1200 @subsubsection VC Directory Commands
1202 Emacs provides several commands for navigating the VC Directory
1203 buffer, and for marking files as belonging to the current VC
1209 Move point to the next entry (@code{vc-dir-next-line}).
1212 Move point to the previous entry (@code{vc-dir-previous-line}).
1215 Move to the next directory entry (@code{vc-dir-next-directory}).
1218 Move to the previous directory entry
1219 (@code{vc-dir-previous-directory}).
1223 Visit the file or directory listed on the current line
1224 (@code{vc-dir-find-file}).
1227 Visit the file or directory on the current line, in a separate window
1228 (@code{vc-dir-find-file-other-window}).
1231 Mark the file or directory on the current line (@code{vc-dir-mark}),
1232 putting it in the current VC fileset. If the region is active, mark
1233 all files in the region.
1235 A file cannot be marked with this command if it is already in a marked
1236 directory, or one of its subdirectories. Similarly, a directory
1237 cannot be marked with this command if any file in its tree is marked.
1240 If point is on a file entry, mark all files with the same status; if
1241 point is on a directory entry, mark all files in that directory tree
1242 (@code{vc-dir-mark-all-files}). With a prefix argument, mark all
1243 listed files and directories.
1246 Quit the VC Directory buffer, and bury it (@code{quit-window}).
1249 Unmark the file or directory on the current line. If the region is
1250 active, unmark all the files in the region (@code{vc-dir-unmark}).
1253 If point is on a file entry, unmark all files with the same status; if
1254 point is on a directory entry, unmark all files in that directory tree
1255 (@code{vc-dir-unmark-all-files}). With a prefix argument, unmark all
1256 files and directories.
1259 Hide files with @samp{up-to-date} status
1260 (@code{vc-dir-hide-up-to-date}). With a prefix argument, hide items
1261 whose state is that of the item at point.
1265 @findex vc-dir-mark-all-files
1266 While in the VC Directory buffer, all the files that you mark with
1267 @kbd{m} (@code{vc-dir-mark}) or @kbd{M} (@code{vc-dir-mark}) are in
1268 the current VC fileset. If you mark a directory entry with @kbd{m},
1269 all the listed files in that directory tree are in the current VC
1270 fileset. The files and directories that belong to the current VC
1271 fileset are indicated with a @samp{*} character in the VC Directory
1272 buffer, next to their VC status. In this way, you can set up a
1273 multi-file VC fileset to be acted on by VC commands like @w{@kbd{C-x v
1274 v}} (@pxref{Basic VC Editing}), @w{@kbd{C-x v =}} (@pxref{Old
1275 Revisions}), and @w{@kbd{C-x v u}} (@pxref{VC Undo}).
1277 The VC Directory buffer also defines some single-key shortcuts for
1278 VC commands with the @kbd{C-x v} prefix: @kbd{=}, @kbd{+}, @kbd{l},
1279 @kbd{i}, @kbd{D}, @kbd{L}, @kbd{G}, @kbd{I} and @kbd{v}.
1281 For example, you can commit a set of edited files by opening a VC
1282 Directory buffer, where the files are listed with the @samp{edited}
1283 status; marking the files; and typing @kbd{v} or @kbd{C-x v v}
1284 (@code{vc-next-action}). If the version control system is
1285 changeset-based, Emacs will commit the files in a single revision.
1287 While in the VC Directory buffer, you can also perform search and
1288 replace on the current VC fileset, with the following commands:
1292 Search the fileset (@code{vc-dir-search}).
1295 Do a regular expression query replace on the fileset
1296 (@code{vc-dir-query-replace-regexp}).
1299 Do an incremental search on the fileset (@code{vc-dir-isearch}).
1302 Do an incremental regular expression search on the fileset
1303 (@code{vc-dir-isearch-regexp}).
1307 Apart from acting on multiple files, these commands behave much like
1308 their single-buffer counterparts (@pxref{Search}).
1310 @cindex stashes in version control
1311 @cindex shelves in version control
1312 The above commands are also available via the menu bar, and via a
1313 context menu invoked by @kbd{Mouse-2}. Furthermore, some VC backends
1314 use the menu to provide extra backend-specific commands. For example,
1315 Git and Bazaar allow you to manipulate @dfn{stashes} and @dfn{shelves}
1316 (where are a way to temporarily put aside uncommitted changes, and
1317 bring them back at a later time).
1320 @subsection Version Control Branches
1321 @cindex branch (version control)
1323 One use of version control is to support multiple independent lines
1324 of development, which are called @dfn{branches}. Amongst other
1325 things, branches can be used for maintaining separate stable and
1326 development versions of a program, and for developing unrelated
1327 features in isolation from one another.
1329 VC's support for branch operations is currently fairly limited. For
1330 decentralized version control systems, it provides commands for
1331 @dfn{updating} one branch with the contents of another, and for
1332 @dfn{merging} the changes made to two different branches
1333 (@pxref{Merging}). For centralized version control systems, it
1334 supports checking out different branches and committing into new or
1338 * Switching Branches:: How to get to another existing branch.
1339 * Pulling / Pushing:: Receiving/sending changes from/to elsewhere.
1340 * Merging:: Transferring changes between branches.
1341 * Creating Branches:: How to start a new branch.
1344 @node Switching Branches
1345 @subsubsection Switching between Branches
1347 The various version control systems differ in how branches are
1348 implemented, and these differences cannot be entirely concealed by VC.
1350 On some decentralized version control systems, including Bazaar and
1351 Mercurial in its normal mode of operation, each branch has its own
1352 working directory tree, so switching between branches just involves
1353 switching directories. On Git, branches are normally @dfn{co-located}
1354 in the same directory, and switching between branches is done using
1355 the @command{git checkout} command, which changes the contents of the
1356 working tree to match the branch you switch to. Bazaar also supports
1357 co-located branches, in which case the @command{bzr switch} command
1358 will switch branches in the current directory. With Subversion, you
1359 switch to another branch using the @command{svn switch} command.
1361 The VC command to switch to another branch in the current directory
1362 is @kbd{C-x v r @var{branch-name} @key{RET}} (@code{vc-retrieve-tag}).
1364 On centralized version control systems, you can also switch between
1365 branches by typing @kbd{C-u C-x v v} in an up-to-date work file
1366 (@pxref{Advanced C-x v v}), and entering the revision ID for a
1367 revision on another branch. On CVS, for instance, revisions on the
1368 @dfn{trunk} (the main line of development) normally have IDs of the
1369 form 1.1, 1.2, 1.3, @dots{}, while the first branch created from (say)
1370 revision 1.2 has revision IDs 1.2.1.1, 1.2.1.2, @dots{}, the second
1371 branch created from revision 1.2 has revision IDs 1.2.2.1, 1.2.2.2,
1372 @dots{}, and so forth. You can also specify the @dfn{branch ID},
1373 which is a branch revision ID omitting its final component
1374 (e.g., 1.2.1), to switch to the latest revision on that branch.
1376 On a locking-based system, switching to a different branch also
1377 unlocks (write-protects) the working tree.
1379 Once you have switched to a branch, VC commands will apply to that
1380 branch until you switch away; for instance, any VC filesets that you
1381 commit will be committed to that specific branch.
1383 @node Pulling / Pushing
1384 @subsubsection Pulling/Pushing Changes into/from a Branch
1388 On a decentralized version control system, update another location
1389 with changes from the current branch (a.k.a. ``push'' changes). This
1390 concept does not exist for centralized version control systems
1393 On a decentralized version control system, update the current branch
1394 by ``pulling in'' changes from another location.
1396 On a centralized version control system, update the current VC
1402 On a decentralized version control system, the command @kbd{C-x v P}
1403 (@code{vc-push}) updates another location with changes from the
1404 current branch. With a prefix argument, it prompts for the exact
1405 version control command to run, which lets you specify where to push
1406 changes; the default is @command{bzr push} with Bazaar, @command{git
1407 push} with Git, and @command{hg push} with Mercurial. The default
1408 commands always push to a default location determined by the version
1409 control system from your branch configuration.
1411 Prior to pushing, you can use @kbd{C-x v O} (@code{vc-log-outgoing})
1412 to view a log buffer of the changes to be sent. @xref{VC Change Log}.
1414 @cindex bound branch (Bazaar VCS)
1415 This command is currently supported only by Bazaar, Git, and Mercurial.
1416 The concept of ``pushing'' does not exist for centralized version
1417 control systems, where this operation is a part of committing a
1418 changeset, so invoking this command on a centralized VCS signals an
1419 error. This command also signals an error when attempted in a Bazaar
1420 @dfn{bound branch}, where committing a changeset automatically pushes
1421 the changes to the remote repository to which the local branch is
1426 On a decentralized version control system, the command @kbd{C-x v +}
1427 (@code{vc-pull}) updates the current branch and working tree. It is
1428 typically used to update a copy of a remote branch. If you supply a
1429 prefix argument, the command prompts for the exact version control
1430 command to use, which lets you specify where to pull changes from.
1431 Otherwise, it pulls from a default location determined by the version
1434 Amongst decentralized version control systems, @kbd{C-x v +} is
1435 currently supported only by Bazaar, Git, and Mercurial. With Bazaar,
1436 it calls @command{bzr pull} for ordinary branches (to pull from a
1437 master branch into a mirroring branch), and @command{bzr update} for a
1438 bound branch (to pull from a central repository). With Git, it calls
1439 @command{git pull} to fetch changes from a remote repository and merge
1440 it into the current branch. With Mercurial, it calls @command{hg pull
1441 -u} to fetch changesets from the default remote repository and update
1442 the working directory.
1444 Prior to pulling, you can use @kbd{C-x v I} (@code{vc-log-incoming})
1445 to view a log buffer of the changes to be applied. @xref{VC Change
1448 On a centralized version control system like CVS, @kbd{C-x v +}
1449 updates the current VC fileset from the repository.
1452 @subsubsection Merging Branches
1453 @cindex merging changes
1457 On a decentralized version control system, merge changes from another
1458 branch into the current one.
1460 On a centralized version control system, merge changes from another
1461 branch into the current VC fileset.
1464 While developing a branch, you may sometimes need to @dfn{merge} in
1465 changes that have already been made in another branch. This is not a
1466 trivial operation, as overlapping changes may have been made to the
1469 On a decentralized version control system, merging is done with the
1470 command @kbd{C-x v m} (@code{vc-merge}). On Bazaar, this prompts for
1471 the exact arguments to pass to @command{bzr merge}, offering a
1472 sensible default if possible. On Git, this prompts for the name of a
1473 branch to merge from, with completion (based on the branch names known
1474 to the current repository). The output from running the merge command
1475 is shown in a separate buffer.
1477 On a centralized version control system like CVS, @kbd{C-x v m}
1478 prompts for a branch ID, or a pair of revision IDs (@pxref{Switching
1479 Branches}); then it finds the changes from that branch, or the changes
1480 between the two revisions you specified, and merges those changes into
1481 the current VC fileset. If you just type @key{RET}, Emacs simply
1482 merges any changes that were made on the same branch since you checked
1486 @cindex resolving conflicts
1487 Immediately after performing a merge, only the working tree is
1488 modified, and you can review the changes produced by the merge with
1489 @kbd{C-x v D} and related commands (@pxref{Old Revisions}). If the
1490 two branches contained overlapping changes, merging produces a
1491 @dfn{conflict}; a warning appears in the output of the merge command,
1492 and @dfn{conflict markers} are inserted into each affected work file,
1493 surrounding the two sets of conflicting changes. You must then
1494 resolve the conflict by editing the conflicted files. Once you are
1495 done, the modified files must be committed in the usual way for the
1496 merge to take effect (@pxref{Basic VC Editing}).
1498 @node Creating Branches
1499 @subsubsection Creating New Branches
1501 On centralized version control systems like CVS, Emacs supports
1502 creating new branches as part of a commit operation. When committing
1503 a modified VC fileset, type @kbd{C-u C-x v v} (@code{vc-next-action}
1504 with a prefix argument; @pxref{Advanced C-x v v}). Then Emacs prompts
1505 for a revision ID for the new revision. You should specify a suitable
1506 branch ID for a branch starting at the current revision. For example,
1507 if the current revision is 2.5, the branch ID should be 2.5.1, 2.5.2,
1508 and so on, depending on the number of existing branches at that point.
1510 To create a new branch at an older revision (one that is no longer
1511 the head of a branch), first select that revision (@pxref{Switching
1512 Branches}). Your procedure will then differ depending on whether you
1513 are using a locking or merging-based VCS.
1515 On a locking VCS, you will need to lock the old revision branch with
1516 @kbd{C-x v v}. You'll be asked to confirm, when you lock the old
1517 revision, that you really mean to create a new branch---if you say no,
1518 you'll be offered a chance to lock the latest revision instead. On a
1519 merging-based VCS you will skip this step.
1521 Then make your changes and type @kbd{C-x v v} again to commit a new
1522 revision. This creates a new branch starting from the selected
1525 After the branch is created, subsequent commits create new revisions
1526 on that branch. To leave the branch, you must explicitly select a
1527 different revision with @kbd{C-u C-x v v}.
1530 @include vc1-xtra.texi
1534 @section Change Logs
1537 Many software projects keep a @dfn{change log}. This is a file,
1538 normally named @file{ChangeLog}, containing a chronological record of
1539 when and how the program was changed. Sometimes, these files are
1540 automatically generated from the change log entries stored in version
1541 control systems, or are used to generate these change log entries.
1542 Sometimes, there are several change log files, each recording the
1543 changes in one directory or directory tree.
1546 * Change Log Commands:: Commands for editing change log files.
1547 * Format of ChangeLog:: What the change log file looks like.
1550 @node Change Log Commands
1551 @subsection Change Log Commands
1554 @findex add-change-log-entry-other-window
1555 The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
1556 file for the file you are editing
1557 (@code{add-change-log-entry-other-window}). If that file is actually
1558 a backup file, it makes an entry appropriate for the file's
1559 parent---that is useful for making log entries for functions that
1560 have been deleted in the current version.
1562 @kbd{C-x 4 a} visits the change log file and creates a new entry
1563 unless the most recent entry is for today's date and your name. It
1564 also creates a new item for the current file. For many languages, it
1565 can even guess the name of the function or other object that was
1568 @vindex add-log-keep-changes-together
1569 When the variable @code{add-log-keep-changes-together} is
1570 non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file
1571 rather than starting a new item.
1573 You can combine multiple changes of the same nature. If you don't
1574 enter any text after the initial @kbd{C-x 4 a}, any subsequent
1575 @kbd{C-x 4 a} adds another symbol to the change log entry.
1577 @vindex add-log-always-start-new-record
1578 If @code{add-log-always-start-new-record} is non-@code{nil},
1579 @kbd{C-x 4 a} always makes a new entry, even if the last entry
1580 was made by you and on the same date.
1582 @vindex change-log-version-info-enabled
1583 @vindex change-log-version-number-regexp-list
1584 @cindex file version in change log entries
1585 If the value of the variable @code{change-log-version-info-enabled}
1586 is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the
1587 change log entry. It finds the version number by searching the first
1588 ten percent of the file, using regular expressions from the variable
1589 @code{change-log-version-number-regexp-list}.
1591 @cindex Change Log mode
1592 @findex change-log-mode
1593 The change log file is visited in Change Log mode. In this major
1594 mode, each bunch of grouped items counts as one paragraph, and each
1595 entry is considered a page. This facilitates editing the entries.
1596 @kbd{C-j} and auto-fill indent each new line like the previous line;
1597 this is convenient for entering the contents of an entry.
1599 You can use the @code{next-error} command (by default bound to
1600 @kbd{C-x `}) to move between entries in the Change Log, when Change
1601 Log mode is on. You will jump to the actual site in the file that was
1602 changed, not just to the next Change Log entry. You can also use
1603 @code{previous-error} to move back in the same list.
1605 @findex change-log-merge
1606 You can use the command @kbd{M-x change-log-merge} to merge other
1607 log files into a buffer in Change Log Mode, preserving the date
1608 ordering of entries.
1610 Version control systems are another way to keep track of changes in
1611 your program and keep a change log. In the VC log buffer, typing
1612 @kbd{C-c C-a} (@code{log-edit-insert-changelog}) inserts the relevant
1613 Change Log entry, if one exists. @xref{Log Buffer}.
1615 @node Format of ChangeLog
1616 @subsection Format of ChangeLog
1618 A change log entry starts with a header line that contains the
1619 current date, your name (taken from the variable
1620 @code{add-log-full-name}), and your email address (taken from the
1621 variable @code{add-log-mailing-address}). Aside from these header
1622 lines, every line in the change log starts with a space or a tab. The
1623 bulk of the entry consists of @dfn{items}, each of which starts with a
1624 line starting with whitespace and a star. Here are two entries, both
1625 dated in May 1993, with two items and one item respectively.
1631 1993-05-25 Richard Stallman <rms@@gnu.org>
1633 * man.el: Rename symbols 'man-*' to 'Man-*'.
1634 (manual-entry): Make prompt string clearer.
1636 * simple.el (blink-matching-paren-distance):
1637 Change default to 12,000.
1639 1993-05-24 Richard Stallman <rms@@gnu.org>
1641 * vc.el (minor-mode-map-alist): Don't use it if it's void.
1642 (vc-cancel-version): Doc fix.
1645 One entry can describe several changes; each change should have its
1646 own item, or its own line in an item. Normally there should be a
1647 blank line between items. When items are related (parts of the same
1648 change, in different places), group them by leaving no blank line
1651 You should put a copyright notice and permission notice at the
1652 end of the change log file. Here is an example:
1655 Copyright 1997, 1998 Free Software Foundation, Inc.
1656 Copying and distribution of this file, with or without modification, are
1657 permitted provided the copyright notice and this notice are preserved.
1661 Of course, you should substitute the proper years and copyright holder.
1664 @section Tags Tables
1665 @cindex tags and tag tables
1667 A @dfn{tag} is a reference to a subunit in a program or in a
1668 document. In source code, tags reference syntactic elements of the
1669 program: functions, subroutines, data types, macros, etc. In a
1670 document, tags reference chapters, sections, appendices, etc. Each
1671 tag specifies the name of the file where the corresponding subunit is
1672 defined, and the position of the subunit's definition in that file.
1674 A @dfn{tags table} records the tags extracted by scanning the source
1675 code of a certain program or a certain document. Tags extracted from
1676 generated files reference the original files, rather than the
1677 generated files that were scanned during tag extraction. Examples of
1678 generated files include C files generated from Cweb source files, from
1679 a Yacc parser, or from Lex scanner definitions; @file{.i} preprocessed
1680 C files; and Fortran files produced by preprocessing @file{.fpp}
1684 To produce a tags table, you run the @command{etags} shell command
1685 on a document or the source code file. The @samp{etags} program
1686 writes the tags to a @dfn{tags table file}, or @dfn{tags file} in
1687 short. The conventional name for a tags file is @file{TAGS}@.
1688 @xref{Create Tags Table}.
1690 Emacs provides many commands for searching and replacing using the
1691 information recorded in tags tables. For instance, the @kbd{M-.}
1692 (@code{find-tag}) jumps to the location of a specified function
1693 definition in its source file. @xref{Find Tag}.
1695 @cindex C++ class browser, tags
1697 @cindex class browser, C++
1699 The Ebrowse facility is similar to @command{etags} but specifically
1700 tailored for C++. @xref{Top,, Ebrowse, ebrowse, Ebrowse User's
1701 Manual}. The Semantic package provides another way to generate and
1702 use tags, separate from the @command{etags} facility.
1706 * Tag Syntax:: Tag syntax for various types of code and text files.
1707 * Create Tags Table:: Creating a tags table with @command{etags}.
1708 * Etags Regexps:: Create arbitrary tags using regular expressions.
1709 * Select Tags Table:: How to visit a tags table.
1710 * Find Tag:: Commands to find the definition of a specific tag.
1711 * Tags Search:: Using a tags table for searching and replacing.
1712 * List Tags:: Using tags for completion, and listing them.
1716 @subsection Source File Tag Syntax
1718 Here is how tag syntax is defined for the most popular languages:
1722 In C code, any C function or typedef is a tag, and so are definitions of
1723 @code{struct}, @code{union} and @code{enum}.
1724 @code{#define} macro definitions, @code{#undef} and @code{enum}
1726 tags, unless you specify @samp{--no-defines} when making the tags table.
1727 Similarly, global variables are tags, unless you specify
1728 @samp{--no-globals}, and so are struct members, unless you specify
1729 @samp{--no-members}. Use of @samp{--no-globals}, @samp{--no-defines}
1730 and @samp{--no-members} can make the tags table file much smaller.
1732 You can tag function declarations and external variables in addition
1733 to function definitions by giving the @samp{--declarations} option to
1737 In C++ code, in addition to all the tag constructs of C code, member
1738 functions are also recognized; member variables are also recognized,
1739 unless you use the @samp{--no-members} option. Tags for variables and
1740 functions in classes are named @samp{@var{class}::@var{variable}} and
1741 @samp{@var{class}::@var{function}}. @code{operator} definitions have
1742 tag names like @samp{operator+}.
1745 In Java code, tags include all the constructs recognized in C++, plus
1746 the @code{interface}, @code{extends} and @code{implements} constructs.
1747 Tags for variables and functions in classes are named
1748 @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
1751 In @LaTeX{} documents, the arguments for @code{\chapter},
1752 @code{\section}, @code{\subsection}, @code{\subsubsection},
1753 @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite},
1754 @code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry},
1755 @code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand},
1756 @code{\newenvironment} and @code{\renewenvironment} are tags.
1758 Other commands can make tags as well, if you specify them in the
1759 environment variable @env{TEXTAGS} before invoking @command{etags}. The
1760 value of this environment variable should be a colon-separated list of
1761 command names. For example,
1764 TEXTAGS="mycommand:myothercommand"
1769 specifies (using Bourne shell syntax) that the commands
1770 @samp{\mycommand} and @samp{\myothercommand} also define tags.
1773 In Lisp code, any function defined with @code{defun}, any variable
1774 defined with @code{defvar} or @code{defconst}, and in general the
1775 first argument of any expression that starts with @samp{(def} in
1776 column zero is a tag. As an exception, expressions of the form
1777 @code{(defvar @var{foo})} are treated as declarations, and are only
1778 tagged if the @samp{--declarations} option is given.
1781 In Scheme code, tags include anything defined with @code{def} or with a
1782 construct whose name starts with @samp{def}. They also include variables
1783 set with @code{set!} at top level in the file.
1786 Several other languages are also supported:
1791 In Ada code, functions, procedures, packages, tasks and types are
1792 tags. Use the @samp{--packages-only} option to create tags for
1795 In Ada, the same name can be used for different kinds of entity
1796 (e.g., for a procedure and for a function). Also, for things like
1797 packages, procedures and functions, there is the spec (i.e., the
1798 interface) and the body (i.e., the implementation). To make it
1799 easier to pick the definition you want, Ada tag name have suffixes
1800 indicating the type of entity:
1817 Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
1818 directly to the body of the package @code{bidule}, while @kbd{M-x
1819 find-tag @key{RET} bidule @key{RET}} will just search for any tag
1823 In assembler code, labels appearing at the start of a line,
1824 followed by a colon, are tags.
1827 In Bison or Yacc input files, each rule defines as a tag the nonterminal
1828 it constructs. The portions of the file that contain C code are parsed
1832 In Cobol code, tags are paragraph names; that is, any word starting in
1833 column 8 and followed by a period.
1836 In Erlang code, the tags are the functions, records and macros defined
1840 In Fortran code, functions, subroutines and block data are tags.
1843 In HTML input files, the tags are the @code{title} and the @code{h1},
1844 @code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchors
1845 and all occurrences of @code{id=}.
1848 In Lua input files, all functions are tags.
1851 In makefiles, targets are tags; additionally, variables are tags
1852 unless you specify @samp{--no-globals}.
1855 In Objective C code, tags include Objective C definitions for classes,
1856 class categories, methods and protocols. Tags for variables and
1857 functions in classes are named @samp{@var{class}::@var{variable}} and
1858 @samp{@var{class}::@var{function}}.
1861 In Pascal code, the tags are the functions and procedures defined in
1865 In Perl code, the tags are the packages, subroutines and variables
1866 defined by the @code{package}, @code{sub}, @code{use constant},
1867 @code{my}, and @code{local} keywords. Use @samp{--globals} if you
1868 want to tag global variables. Tags for subroutines are named
1869 @samp{@var{package}::@var{sub}}. The name for subroutines defined in
1870 the default package is @samp{main::@var{sub}}.
1873 In PHP code, tags are functions, classes and defines. Vars are tags
1874 too, unless you use the @samp{--no-members} option.
1877 In PostScript code, the tags are the functions.
1880 In Prolog code, tags are predicates and rules at the beginning of
1884 In Python code, @code{def} or @code{class} at the beginning of a line
1888 You can also generate tags based on regexp matching (@pxref{Etags
1889 Regexps}) to handle other formats and languages.
1891 @node Create Tags Table
1892 @subsection Creating Tags Tables
1893 @cindex @command{etags} program
1895 The @command{etags} program is used to create a tags table file. It knows
1896 the syntax of several languages, as described in
1898 the previous section.
1903 Here is how to run @command{etags}:
1906 etags @var{inputfiles}@dots{}
1910 The @command{etags} program reads the specified files, and writes a tags
1911 table named @file{TAGS} in the current working directory. You can
1912 optionally specify a different file name for the tags table by using the
1913 @samp{--output=@var{file}} option; specifying @file{-} as a file name
1914 prints the tags table to standard output.
1916 If the specified files don't exist, @command{etags} looks for
1917 compressed versions of them and uncompresses them to read them. Under
1918 MS-DOS, @command{etags} also looks for file names like @file{mycode.cgz}
1919 if it is given @samp{mycode.c} on the command line and @file{mycode.c}
1922 If the tags table becomes outdated due to changes in the files
1923 described in it, you can update it by running the @command{etags}
1924 program again. If the tags table does not record a tag, or records it
1925 for the wrong file, then Emacs will not be able to find that
1926 definition until you update the tags table. But if the position
1927 recorded in the tags table becomes a little bit wrong (due to other
1928 editing), Emacs will still be able to find the right position, with a
1931 Thus, there is no need to update the tags table after each edit.
1932 You should update a tags table when you define new tags that you want
1933 to have listed, or when you move tag definitions from one file to
1934 another, or when changes become substantial.
1936 You can make a tags table @dfn{include} another tags table, by
1937 passing the @samp{--include=@var{file}} option to @command{etags}. It
1938 then covers all the files covered by the included tags file, as well
1941 If you specify the source files with relative file names when you run
1942 @command{etags}, the tags file will contain file names relative to the
1943 directory where the tags file was initially written. This way, you can
1944 move an entire directory tree containing both the tags file and the
1945 source files, and the tags file will still refer correctly to the source
1946 files. If the tags file is @file{-} or is in the @file{/dev} directory,
1947 however, the file names are
1948 made relative to the current working directory. This is useful, for
1949 example, when writing the tags to @file{/dev/stdout}.
1951 When using a relative file name, it should not be a symbolic link
1952 pointing to a tags file in a different directory, because this would
1953 generally render the file names invalid.
1955 If you specify absolute file names as arguments to @command{etags}, then
1956 the tags file will contain absolute file names. This way, the tags file
1957 will still refer to the same files even if you move it, as long as the
1958 source files remain in the same place. Absolute file names start with
1959 @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
1961 When you want to make a tags table from a great number of files,
1962 you may have problems listing them on the command line, because some
1963 systems have a limit on its length. You can circumvent this limit by
1964 telling @command{etags} to read the file names from its standard
1965 input, by typing a dash in place of the file names, like this:
1968 find . -name "*.[chCH]" -print | etags -
1971 @command{etags} recognizes the language used in an input file based
1972 on its file name and contents. You can specify the language
1973 explicitly with the @samp{--language=@var{name}} option. You can
1974 intermix these options with file names; each one applies to the file
1975 names that follow it. Specify @samp{--language=auto} to tell
1976 @command{etags} to resume guessing the language from the file names
1977 and file contents. Specify @samp{--language=none} to turn off
1978 language-specific processing entirely; then @command{etags} recognizes
1979 tags by regexp matching alone (@pxref{Etags Regexps}).
1981 The option @samp{--parse-stdin=@var{file}} is mostly useful when
1982 calling @command{etags} from programs. It can be used (only once) in
1983 place of a file name on the command line. @command{etags} will read from
1984 standard input and mark the produced tags as belonging to the file
1987 @samp{etags --help} outputs the list of the languages @command{etags}
1988 knows, and the file name rules for guessing the language. It also prints
1989 a list of all the available @command{etags} options, together with a short
1990 explanation. If followed by one or more @samp{--language=@var{lang}}
1991 options, it outputs detailed information about how tags are generated for
1995 @subsection Etags Regexps
1997 The @samp{--regex} option to @command{etags} allows tags to be
1998 recognized by regular expression matching. You can intermix this
1999 option with file names; each one applies to the source files that
2000 follow it. If you specify multiple @samp{--regex} options, all of
2001 them are used in parallel. The syntax is:
2004 --regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers}
2008 The essential part of the option value is @var{tagregexp}, the regexp
2009 for matching tags. It is always used anchored, that is, it only
2010 matches at the beginning of a line. If you want to allow indented
2011 tags, use a regexp that matches initial whitespace; start it with
2014 In these regular expressions, @samp{\} quotes the next character, and
2015 all the GCC character escape sequences are supported (@samp{\a} for
2016 bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for
2017 escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for
2018 carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab).
2020 Ideally, @var{tagregexp} should not match more characters than are
2021 needed to recognize what you want to tag. If the syntax requires you
2022 to write @var{tagregexp} so it matches more characters beyond the tag
2023 itself, you should add a @var{nameregexp}, to pick out just the tag.
2024 This will enable Emacs to find tags more accurately and to do
2025 completion on tag names more reliably. You can find some examples
2028 The @var{modifiers} are a sequence of zero or more characters that
2029 modify the way @command{etags} does the matching. A regexp with no
2030 modifiers is applied sequentially to each line of the input file, in a
2031 case-sensitive way. The modifiers and their meanings are:
2035 Ignore case when matching this regexp.
2037 Match this regular expression against the whole file, so that
2038 multi-line matches are possible.
2040 Match this regular expression against the whole file, and allow
2041 @samp{.} in @var{tagregexp} to match newlines.
2044 The @samp{-R} option cancels all the regexps defined by preceding
2045 @samp{--regex} options. It too applies to the file names following
2046 it. Here's an example:
2049 etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
2050 bar.ber -R --lang=lisp los.er
2054 Here @command{etags} chooses the parsing language for @file{voo.doo} and
2055 @file{bar.ber} according to their contents. @command{etags} also uses
2056 @var{reg1} to recognize additional tags in @file{voo.doo}, and both
2057 @var{reg1} and @var{reg2} to recognize additional tags in
2058 @file{bar.ber}. @var{reg1} is checked against each line of
2059 @file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while
2060 @var{reg2} is checked against the whole @file{bar.ber} file,
2061 permitting multi-line matches, in a case-sensitive way. @command{etags}
2062 uses only the Lisp tags rules, with no user-specified regexp matching,
2063 to recognize tags in @file{los.er}.
2065 You can restrict a @samp{--regex} option to match only files of a
2066 given language by using the optional prefix @var{@{language@}}.
2067 (@samp{etags --help} prints the list of languages recognized by
2068 @command{etags}.) This is particularly useful when storing many
2069 predefined regular expressions for @command{etags} in a file. The
2070 following example tags the @code{DEFVAR} macros in the Emacs source
2071 files, for the C language only:
2074 --regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/'
2078 When you have complex regular expressions, you can store the list of
2079 them in a file. The following option syntax instructs @command{etags} to
2080 read two files of regular expressions. The regular expressions
2081 contained in the second file are matched without regard to case.
2084 --regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file}
2088 A regex file for @command{etags} contains one regular expression per
2089 line. Empty lines, and lines beginning with space or tab are ignored.
2090 When the first character in a line is @samp{@@}, @command{etags} assumes
2091 that the rest of the line is the name of another file of regular
2092 expressions; thus, one such file can include another file. All the
2093 other lines are taken to be regular expressions. If the first
2094 non-whitespace text on the line is @samp{--}, that line is a comment.
2096 For example, we can create a file called @samp{emacs.tags} with the
2100 -- This is for GNU Emacs C source files
2101 @{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
2105 and then use it like this:
2108 etags --regex=@@emacs.tags *.[ch] */*.[ch]
2111 Here are some more examples. The regexps are quoted to protect them
2112 from shell interpretation.
2120 etags --language=none \
2121 --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
2122 --regex='/###key \(.*\)/\1/' \
2123 --regex='/[ \t]*global[ \t].*/' \
2128 Note that tags are not generated for scripts, so that you have to add
2129 a line by yourself of the form @samp{###key @var{scriptname}} if you
2136 etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
2143 etags --language=none \
2144 --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
2145 --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
2146 \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
2150 @node Select Tags Table
2151 @subsection Selecting a Tags Table
2153 @findex visit-tags-table
2154 Emacs has at any time one @dfn{selected} tags table. All the
2155 commands for working with tags tables use the selected one. To select
2156 a tags table, type @kbd{M-x visit-tags-table}, which reads the tags
2157 table file name as an argument, with @file{TAGS} in the default
2158 directory as the default.
2160 @vindex tags-file-name
2161 Emacs does not actually read in the tags table contents until you
2162 try to use them; all @code{visit-tags-table} does is store the file
2163 name in the variable @code{tags-file-name}, and setting the variable
2164 yourself is just as good. The variable's initial value is @code{nil};
2165 that value tells all the commands for working with tags tables that
2166 they must ask for a tags table file name to use.
2168 Using @code{visit-tags-table} when a tags table is already loaded
2169 gives you a choice: you can add the new tags table to the current list
2170 of tags tables, or start a new list. The tags commands use all the tags
2171 tables in the current list. If you start a new list, the new tags table
2172 is used @emph{instead} of others. If you add the new table to the
2173 current list, it is used @emph{as well as} the others.
2175 @vindex tags-table-list
2176 You can specify a precise list of tags tables by setting the variable
2177 @code{tags-table-list} to a list of strings, like this:
2179 @c keep this on two lines for formatting in smallbook
2182 (setq tags-table-list
2183 '("~/emacs" "/usr/local/lib/emacs/src"))
2188 This tells the tags commands to look at the @file{TAGS} files in your
2189 @file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src}
2190 directory. The order depends on which file you are in and which tags
2191 table mentions that file, as explained above.
2193 Do not set both @code{tags-file-name} and @code{tags-table-list}.
2196 @subsection Finding a Tag
2198 The most important thing that a tags table enables you to do is to find
2199 the definition of a specific tag.
2202 @item M-.@: @var{tag} @key{RET}
2203 Find first definition of @var{tag} (@code{find-tag}).
2205 Find next alternate definition of last tag specified.
2207 Go back to previous tag found.
2208 @item C-M-. @var{pattern} @key{RET}
2209 Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}).
2211 Find the next tag whose name matches the last pattern used.
2212 @item C-x 4 .@: @var{tag} @key{RET}
2213 Find first definition of @var{tag}, but display it in another window
2214 (@code{find-tag-other-window}).
2215 @item C-x 5 .@: @var{tag} @key{RET}
2216 Find first definition of @var{tag}, and create a new frame to select the
2217 buffer (@code{find-tag-other-frame}).
2219 Pop back to where you previously invoked @kbd{M-.} and friends.
2224 @kbd{M-.}@: (@code{find-tag}) prompts for a tag name and jumps to
2225 its source definition. It works by searching through the tags table
2226 for that tag's file and approximate character position, visiting that
2227 file, and searching for the tag definition at ever-increasing
2228 distances away from the recorded approximate position.
2230 When entering the tag argument to @kbd{M-.}, the usual minibuffer
2231 completion commands can be used (@pxref{Completion}), with the tag
2232 names in the selected tags table as completion candidates. If you
2233 specify an empty argument, the balanced expression in the buffer
2234 before or around point is the default argument. @xref{Expressions}.
2236 You don't need to give @kbd{M-.} the full name of the tag; a part
2237 will do. @kbd{M-.} finds tags which contain that argument as a
2238 substring. However, it prefers an exact match to a substring match.
2239 To find other tags that match the same substring, give @code{find-tag}
2240 a numeric argument, as in @kbd{C-u M-.} or @kbd{M-0 M-.}; this does
2241 not read a tag name, but continues searching the tags table's text for
2242 another tag containing the same substring last used.
2245 @findex find-tag-other-window
2247 @findex find-tag-other-frame
2248 Like most commands that can switch buffers, @code{find-tag} has a
2249 variant that displays the new buffer in another window, and one that
2250 makes a new frame for it. The former is @w{@kbd{C-x 4 .}}
2251 (@code{find-tag-other-window}), and the latter is @w{@kbd{C-x 5 .}}
2252 (@code{find-tag-other-frame}).
2254 To move back to previous tag definitions, use @kbd{C-u - M-.}; more
2255 generally, @kbd{M-.} with a negative numeric argument. Similarly,
2256 @w{@kbd{C-x 4 .}} with a negative argument finds the previous tag
2257 location in another window.
2260 @findex pop-tag-mark
2261 @vindex find-tag-marker-ring-length
2262 As well as going back to places you've found tags recently, you can
2263 go back to places @emph{from where} you found them, using @kbd{M-*}
2264 (@code{pop-tag-mark}). Thus you can find and examine the definition
2265 of something with @kbd{M-.} and then return to where you were with
2268 Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
2269 a depth determined by the variable @code{find-tag-marker-ring-length}.
2271 @findex find-tag-regexp
2273 The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that
2274 match a specified regular expression. It is just like @kbd{M-.} except
2275 that it does regexp matching instead of substring matching.
2278 @subsection Searching and Replacing with Tags Tables
2279 @cindex search and replace in multiple files
2280 @cindex multiple-file search and replace
2282 The commands in this section visit and search all the files listed
2283 in the selected tags table, one by one. For these commands, the tags
2284 table serves only to specify a sequence of files to search. These
2285 commands scan the list of tags tables starting with the first tags
2286 table (if any) that describes the current file, proceed from there to
2287 the end of the list, and then scan from the beginning of the list
2288 until they have covered all the tables in the list.
2291 @item M-x tags-search @key{RET} @var{regexp} @key{RET}
2292 Search for @var{regexp} through the files in the selected tags
2294 @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
2295 Perform a @code{query-replace-regexp} on each file in the selected tags table.
2297 Restart one of the commands above, from the current location of point
2298 (@code{tags-loop-continue}).
2302 @kbd{M-x tags-search} reads a regexp using the minibuffer, then
2303 searches for matches in all the files in the selected tags table, one
2304 file at a time. It displays the name of the file being searched so you
2305 can follow its progress. As soon as it finds an occurrence,
2306 @code{tags-search} returns.
2309 @findex tags-loop-continue
2310 Having found one match, you probably want to find all the rest.
2311 Type @kbd{M-,} (@code{tags-loop-continue}) to resume the
2312 @code{tags-search}, finding one more match. This searches the rest of
2313 the current buffer, followed by the remaining files of the tags table.
2315 @findex tags-query-replace
2316 @kbd{M-x tags-query-replace} performs a single
2317 @code{query-replace-regexp} through all the files in the tags table. It
2318 reads a regexp to search for and a string to replace with, just like
2319 ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
2320 tags-search}, but repeatedly, processing matches according to your
2321 input. @xref{Query Replace}, for more information on query replace.
2323 @vindex tags-case-fold-search
2324 @cindex case-sensitivity and tags search
2325 You can control the case-sensitivity of tags search commands by
2326 customizing the value of the variable @code{tags-case-fold-search}. The
2327 default is to use the same setting as the value of
2328 @code{case-fold-search} (@pxref{Lax Search}).
2330 It is possible to get through all the files in the tags table with a
2331 single invocation of @kbd{M-x tags-query-replace}. But often it is
2332 useful to exit temporarily, which you can do with any input event that
2333 has no special query replace meaning. You can resume the query
2334 replace subsequently by typing @kbd{M-,}; this command resumes the
2335 last tags search or replace command that you did. For instance, to
2336 skip the rest of the current file, you can type @kbd{M-> M-,}.
2338 The commands in this section carry out much broader searches than the
2339 @code{find-tag} family. The @code{find-tag} commands search only for
2340 definitions of tags that match your substring or regexp. The commands
2341 @code{tags-search} and @code{tags-query-replace} find every occurrence
2342 of the regexp, as ordinary search commands and replace commands do in
2345 These commands create buffers only temporarily for the files that they
2346 have to search (those which are not already visited in Emacs buffers).
2347 Buffers in which no match is found are quickly killed; the others
2350 As an alternative to @code{tags-search}, you can run @command{grep}
2351 as a subprocess and have Emacs show you the matching lines one by one.
2352 @xref{Grep Searching}.
2355 @subsection Tags Table Inquiries
2360 Perform completion on the text around point, using the selected tags
2361 table if one is loaded (@code{completion-at-point}).
2362 @item M-x list-tags @key{RET} @var{file} @key{RET}
2363 Display a list of the tags defined in the program file @var{file}.
2364 @item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
2365 Display a list of all tags matching @var{regexp}.
2368 @cindex completion (symbol names)
2369 In most programming language modes, you can type @kbd{C-M-i} or
2370 @kbd{M-@key{TAB}} (@code{completion-at-point}) to complete the symbol
2371 at point. If there is a selected tags table, this command can use it
2372 to generate completion candidates. @xref{Symbol Completion}.
2375 @kbd{M-x list-tags} reads the name of one of the files covered by
2376 the selected tags table, and displays a list of tags defined in that
2377 file. Do not include a directory as part of the file name unless the
2378 file name recorded in the tags table includes a directory.
2380 @findex tags-apropos
2381 @vindex tags-apropos-verbose
2382 @vindex tags-tag-face
2383 @vindex tags-apropos-additional-actions
2384 @kbd{M-x tags-apropos} is like @code{apropos} for tags
2385 (@pxref{Apropos}). It displays a list of tags in the selected tags
2386 table whose entries match @var{regexp}. If the variable
2387 @code{tags-apropos-verbose} is non-@code{nil}, it displays the names
2388 of the tags files together with the tag names. You can customize the
2389 appearance of the output by setting the variable @code{tags-tag-face}
2390 to a face. You can display additional output by customizing the
2391 variable @code{tags-apropos-additional-actions}; see its documentation
2395 @kbd{M-x next-file} visits files covered by the selected tags table.
2396 The first time it is called, it visits the first file covered by the
2397 table. Each subsequent call visits the next covered file, unless a
2398 prefix argument is supplied, in which case it returns to the first
2402 @section Emacs Development Environment
2403 @cindex EDE (Emacs Development Environment)
2404 @cindex Emacs Development Environment
2405 @cindex Integrated development environment
2407 EDE (@dfn{Emacs Development Environment}) is a package that simplifies
2408 the task of creating, building, and debugging large programs with
2409 Emacs. It provides some of the features of an IDE, or @dfn{Integrated
2410 Development Environment}, in Emacs.
2412 This section provides a brief description of EDE usage.
2414 For full details, see @ref{Top, EDE,, ede, Emacs Development Environment}.
2417 For full details on Ede, type @kbd{C-h i} and then select the EDE
2421 EDE is implemented as a global minor mode (@pxref{Minor Modes}). To
2422 enable it, type @kbd{M-x global-ede-mode} or click on the
2423 @samp{Project Support (EDE)} item in the @samp{Tools} menu. You can
2424 also enable EDE each time you start Emacs, by adding the following
2425 line to your initialization file:
2432 Activating EDE adds a menu named @samp{Development} to the menu bar.
2433 Many EDE commands, including the ones described below, can be invoked
2436 EDE organizes files into @dfn{projects}, which correspond to
2437 directory trees. The @dfn{project root} is the topmost directory of a
2438 project. To define a new project, visit a file in the desired project
2439 root and type @kbd{M-x ede-new}. This command prompts for a
2440 @dfn{project type}, which refers to the underlying method that EDE
2441 will use to manage the project (@pxref{Creating a project, EDE,, ede,
2442 Emacs Development Environment}). The most common project types are
2443 @samp{Make}, which uses Makefiles, and @samp{Automake}, which uses GNU
2444 Automake (@pxref{Top, Automake,, automake, Automake}). In both cases,
2445 EDE also creates a file named @file{Project.ede}, which stores
2446 information about the project.
2448 A project may contain one or more @dfn{targets}. A target can be an
2449 object file, executable program, or some other type of file, which is
2450 built from one or more of the files in the project.
2452 To add a new @dfn{target} to a project, type @kbd{C-c . t}
2453 (@code{M-x ede-new-target}). This command also asks if you wish to
2454 add the current file to that target, which means that the target
2455 is to be built from that file. After you have defined a target, you
2456 can add more files to it by typing @kbd{C-c . a}
2457 (@code{ede-add-file}).
2459 To build a target, type @kbd{C-c . c} (@code{ede-compile-target}).
2460 To build all the targets in the project, type @kbd{C-c . C}
2461 (@code{ede-compile-project}). EDE uses the file types to guess how
2462 the target should be built.
2465 @include emerge-xtra.texi