@c This is part of the Emacs manual.
-@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
-@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2011
+@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Maintaining, Abbrevs, Building, Top
@chapter Maintaining Large Programs
This chapter describes Emacs features for maintaining large
-programs. The version control features (@pxref{Version Control}) are
-also particularly useful for this purpose.
+programs.
@menu
-* Change Log:: Maintaining a change history for your program.
-* Format of ChangeLog:: What the change log file looks like.
-* Tags:: Go directly to any function in your program in one
- command. Tags remembers which file it is in.
+* Version Control:: Using version control systems.
+* Change Log:: Maintaining a change history for your program.
+* Tags:: Go directly to any function in your program in one
+ command. Tags remembers which file it is in.
+* EDE:: An integrated development environment for Emacs.
@ifnottex
* Emerge:: A convenient way of merging two versions of a program.
@end ifnottex
@end menu
+@node Version Control
+@section Version Control
+@cindex version control
+
+ A @dfn{version control system} is a program that can record multiple
+versions of a source file, storing information such as the creation
+time of each version, who made it, and a description of what was
+changed.
+
+ The Emacs version control interface is called @dfn{VC}. VC commands
+work with several different version control systems; currently, it
+supports GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS,
+SCCS/CSSC, and Subversion. Of these, the GNU project distributes CVS,
+Arch, RCS, and Bazaar.
+
+ VC is enabled automatically whenever you visit a file governed by a
+version control system. To disable VC entirely, set the customizable
+variable @code{vc-handled-backends} to @code{nil}
+@iftex
+(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
+@end iftex
+@ifnottex
+(@pxref{Customizing VC}).
+@end ifnottex
+
+@menu
+* Introduction to VC:: How version control works in general.
+* VC Mode Line:: How the mode line shows version control status.
+* Basic VC Editing:: How to edit a file under version control.
+* Log Buffer:: Features available in log entry buffers.
+* Old Revisions:: Examining and comparing old versions.
+* Secondary VC Commands:: The commands used a little less frequently.
+* VC Directory Mode:: Listing files managed by version control.
+* Branches:: Multiple lines of development.
+@ifnottex
+* Remote Repositories:: Efficient access to remote CVS servers.
+* Revision Tags:: Symbolic names for revisions.
+* Miscellaneous VC:: Various other commands and features of VC.
+* Customizing VC:: Variables that change VC's behavior.
+@end ifnottex
+@end menu
+
+@node Introduction to VC
+@subsection Introduction to Version Control
+
+ VC allows you to use a version control system from within Emacs,
+integrating the version control operations smoothly with editing. It
+provides a uniform interface for common operations in many version
+control operations.
+
+ Some uncommon or intricate version control operations, such as
+altering repository settings, are not supported in VC. You should
+perform such tasks outside Emacs, e.g. via the command line.
+
+ This section provides a general overview of version control, and
+describes the version control systems that VC supports. You can skip
+this section if you are already familiar with the version control system
+you want to use.
+
+@menu
+* Why Version Control?:: Understanding the problems it addresses.
+* Version Control Systems:: Supported version control back-end systems.
+* VCS Concepts:: Words and concepts related to version control.
+* VCS Merging:: How file conflicts are handled.
+* VCS Changesets:: How changes are grouped.
+* VCS Repositories:: Where version control repositories are stored.
+* Types of Log File:: The VCS log in contrast to the ChangeLog.
+@end menu
+
+@node Why Version Control?
+@subsubsection Understanding the problems it addresses
+
+ Version control systems provide you with three important
+capabilities:
+
+@itemize @bullet
+@item
+@dfn{Reversibility}: the ability to back up to a previous state if you
+discover that some modification you did was a mistake or a bad idea.
+
+@item
+@dfn{Concurrency}: the ability to have many people modifying the same
+collection of files knowing that conflicting modifications can be
+detected and resolved.
+
+@item
+@dfn{History}: the ability to attach historical data to your data,
+such as explanatory comments about the intention behind each change to
+it. Even for a programmer working solo, change histories are an
+important aid to memory; for a multi-person project, they are a
+vitally important form of communication among developers.
+@end itemize
+
+@node Version Control Systems
+@subsubsection Supported Version Control Systems
+
+@cindex back end (version control)
+ VC currently works with many different version control systems,
+which it refers to as @dfn{back ends}:
+
+@itemize @bullet
+
+@cindex SCCS
+@item
+SCCS was the first version control system ever built, and was long ago
+superseded by more advanced ones. VC compensates for certain features
+missing in SCCS (e.g., tag names for releases) by implementing them
+itself. Other VC features, such as multiple branches, are simply
+unavailable. Since SCCS is non-free, we recommend avoiding it.
+
+@cindex CSSC
+@item
+CSSC is a free replacement for SCCS. You should use CSSC only if, for
+some reason, you cannot use a more recent and better-designed version
+control system.
+
+@cindex RCS
+@item
+RCS is the free version control system around which VC was initially
+built. It is relatively primitive: it cannot be used over the
+network, and works at the level of individual files. Almost
+everything you can do with RCS can be done through VC.
+
+@cindex CVS
+@item
+CVS is the free version control system that was, until recently (circa
+2008), used by the majority of free software projects. Nowadays, it
+is slowly being superseded by newer systems. CVS allows concurrent
+multi-user development either locally or over the network. Unlike
+newer systems, it lacks support for atomic commits and file
+moving/renaming. VC supports all basic editing operations under CVS.
+
+@cindex SVN
+@cindex Subversion
+@item
+Subversion (SVN) is a free version control system designed to be
+similar to CVS but without its problems (e.g., it supports atomic
+commits of filesets, and versioning of directories, symbolic links,
+meta-data, renames, copies, and deletes).
+
+@cindex GNU Arch
+@cindex Arch
+@item
+GNU Arch is one of the earliest @dfn{distributed} version control
+systems (the other being Monotone). @xref{VCS Concepts}, for a
+description of distributed version control systems. It is no longer
+under active development, and has been deprecated in favor of Bazaar.
+
+@cindex git
+@item
+Git is a distributed version control system originally invented by
+Linus Torvalds to support development of Linux (his kernel). VC
+supports many common git operations, but others, such as repository
+syncing, must be done from the command line.
+
+@cindex hg
+@cindex Mercurial
+@item
+Mercurial (hg) is a distributed version control system broadly
+resembling git. VC supports most Mercurial commands, with the
+exception of repository sync operations.
+
+@cindex bzr
+@cindex Bazaar
+@item
+Bazaar (bzr) is a distributed version control system that supports
+both repository-based and distributed versioning. VC supports most
+basic editing operations under Bazaar.
+@end itemize
+
+ Previous versions of VC supported a version control system known as
+Meta-CVS. This support was dropped due to limited interest from users
+and developers.
+
+@node VCS Concepts
+@subsubsection Concepts of Version Control
+
+@cindex repository
+@cindex registered file
+ When a file is under version control, we say that it is
+@dfn{registered} in the version control system. The system has a
+@dfn{repository} which stores both the file's present state and its
+change history---enough to reconstruct the current version or any
+earlier version. The repository also contains other information, such
+as @dfn{log entries} that describe the changes made to each file.
+
+@cindex work file
+@cindex checking out files
+ The copy of a version-controlled file that you actually edit is
+called the @dfn{work file}. You can change each work file as you
+would an ordinary file. After you are done with a set of changes, you
+@dfn{commit} (or @dfn{check in}) the changes; this records the changes
+in the repository, along with a descriptive log entry.
+
+@cindex revision
+@cindex revision ID
+ A copy of a file stored in a repository is called a @dfn{revision}.
+The history of a file is a sequence of revisions. Each revision is
+named by a @dfn{revision ID}. The format of the revision ID depends
+on the version control system; in the simplest case, it is just an
+integer.
+
+ To go beyond these basic concepts, you will need to understand three
+aspects in which version control systems differ. As explained in the
+next three sections, they can be lock-based or merge-based; file-based
+or changeset-based; and centralized or decentralized. VC handles all
+these modes of operation, but it cannot hide the differences.
+
+@node VCS Merging
+@subsubsection Merge-based vs lock-based Version Control
+@cindex locking versus merging
+
+ A version control system typically has some mechanism to coordinate
+between users who want to change the same file. There are two ways to
+do this: merging and locking.
+
+ In a version control system that uses merging, each user may check
+out and modify a work file at any time. The system lets you
+@dfn{merge} your work file, which may contain changes that have not
+been committed, with the latest changes that others have committed.
+
+ Older version control systems use a @dfn{locking} scheme instead.
+Here, work files are normally read-only. To edit a file, you ask the
+version control system to make it writable for you by @dfn{locking}
+it; only one user can lock a given file at any given time. This
+procedure is analogous to, but different from, the locking that Emacs
+uses to detect simultaneous editing of ordinary files
+(@pxref{Interlocking}). When you commit your changes, that unlocks
+the file, and the work file becomes read-only again. Other users may
+then lock the file to make their own changes.
+
+ Both locking and merging systems can have problems when multiple
+users try to modify the same file at the same time. Locking systems
+have @dfn{lock conflicts}; a user may try to check a file out and be
+unable to because it is locked. In merging systems, @dfn{merge
+conflicts} happen when you commit a change to a file that conflicts
+with a change committed by someone else after your checkout. Both
+kinds of conflict have to be resolved by human judgment and
+communication. Experience has shown that merging is superior to
+locking, both in convenience to developers and in minimizing the
+number and severity of conflicts that actually occur.
+
+ SCCS always uses locking. RCS is lock-based by default but can be
+told to operate in a merging style. CVS and Subversion are
+merge-based by default but can be told to operate in a locking mode.
+Distributed version control systems, such as GNU Arch, git, and
+Mercurial, are exclusively merging-based.
+
+ VC mode supports both locking and merging version control. The
+terms ``commit'' and ``update'' are used in newer version control
+systems; older lock-based systems use the terms ``check in'' and
+``check out''. VC hides the differences between them as much as
+possible.
+
+@node VCS Changesets
+@subsubsection Changeset-based vs File-based Version Control
+
+@cindex changesets
+ On SCCS, RCS, CVS, and other early version control systems, version
+control operations are @dfn{file-based}: each file has its own comment
+and revision history separate from that of all other files. Newer
+systems, beginning with Subversion, are @dfn{changeset-based}: a
+checkin may include changes to several files, and the entire set of
+changes is handled as a unit. Any comment associated with the change
+does not belong to a single file, but to the changeset itself.
+
+ Changeset-based version control is more flexible and powerful than
+file-based version control; usually, when a change to multiple files
+has to be reversed, it's good to be able to easily identify and remove
+all of it.
+
+@node VCS Repositories
+@subsubsection Decentralized vs Centralized Repositories
+
+@cindex centralized version control
+@cindex decentralized version control
+ Early version control systems were designed around a
+@dfn{centralized} model in which each project has only one repository
+used by all developers. SCCS, RCS, CVS, and Subversion share this
+kind of model. One of its drawbacks is that the repository is a choke
+point for reliability and efficiency.
+
+ GNU Arch pioneered the concept of @dfn{decentralized} version
+control, later implemented in git, Mercurial, and Bazaar. A project
+may have several different repositories, and these systems support a
+sort of super-merge between repositories that tries to reconcile their
+change histories. In effect, there is one repository for each
+developer, and repository merges take the place of commit operations.
+
+ VC helps you manage the traffic between your personal workfiles and
+a repository. Whether the repository is a single master, or one of a
+network of peer repositories, is not something VC has to care about.
+
+@node Types of Log File
+@subsubsection Types of Log File
+@cindex types of log file
+@cindex log File, types of
+@cindex version control log
+
+ Projects that use a version control system can have two types of log
+for changes. One is the log maintained by the version control system:
+each time you commit a change, you fill out a @dfn{log entry} for the
+change (@pxref{Log Buffer}). This is called the @dfn{version control
+log}.
+
+ The other kind of log is the file @file{ChangeLog} (@pxref{Change
+Log}). It provides a chronological record of all changes to a large
+portion of a program---typically one directory and its subdirectories.
+A small program would use one @file{ChangeLog} file; a large program
+may have a @file{ChangeLog} file in each major directory.
+@xref{Change Log}. Programmers have used change logs since long
+before version control systems.
+
+ Changeset-based version systems typically maintain a changeset-based
+modification log for the entire system, which makes change log files
+somewhat redundant. One advantage that they retain is that it is
+sometimes useful to be able to view the transaction history of a
+single directory separately from those of other directories.
+
+ A project maintained with version control can use just the version
+control log, or it can use both kinds of logs. It can handle some
+files one way and some files the other way. Each project has its
+policy, which you should follow.
+
+ When the policy is to use both, you typically want to write an entry
+for each change just once, then put it into both logs. You can write
+the entry in @file{ChangeLog}, then copy it to the log buffer with
+@kbd{C-c C-a} when checking in the change (@pxref{Log Buffer}). Or
+you can write the entry in the log buffer while checking in the
+change, and later use the @kbd{C-x v a} command to copy it to
+@file{ChangeLog}
+@iftex
+(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
+@end iftex
+@ifnottex
+(@pxref{Change Logs and VC}).
+@end ifnottex
+
+@node VC Mode Line
+@subsection Version Control and the Mode Line
+@cindex VC, mode line indicator
+
+ When you visit a file that is under version control, Emacs indicates
+this on the mode line. For example, @samp{Bzr-1223} says that Bazaar
+is used for that file, and the current revision ID is 1223.
+
+ The character between the back-end name and the revision ID
+indicates the status of the work file. In a merge-based version
+control system, a @samp{-} character indicates that the work file is
+unmodified, and @samp{:} indicates that it has been modified.
+@samp{!} indicates that the file contains conflicts as result of a
+recent merge operation (@pxref{Merging}), or that the file was removed
+from the version control. Finally, @samp{?} means that the file is
+under version control, but is missing from the working tree.
+
+ In a lock-based system, @samp{-} indicates an unlocked file, and
+@samp{:} a locked file; if the file is locked by another user (for
+instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
+@samp{@@} means that the file was locally added, but not yet committed
+to the master repository.
+
+ On a graphical display, you can move the mouse over this mode line
+indicator to pop up a ``tool-tip'', which displays a more verbose
+description of the version control status. Pressing @kbd{Mouse-1}
+over the indicator pops up a menu of VC commands, identical to
+@samp{Tools / Version Control} on the menu bar.
+
+@vindex auto-revert-check-vc-info
+ When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is
+under version control, it updates the version control information in
+the mode line. However, Auto Revert mode may not properly update this
+information if the version control status changes without changes to
+the work file, from outside the current Emacs session. If you set
+@code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates
+the version control status information every
+@code{auto-revert-interval} seconds, even if the work file itself is
+unchanged. The resulting CPU usage depends on the version control
+system, but is usually not excessive.
+
+@node Basic VC Editing
+@subsection Basic Editing under Version Control
+
+@cindex filesets, VC
+ Most VC commands operate on @dfn{VC filesets}. A VC fileset is a
+collection of one or more files that a VC operation acts on. When you
+type VC commands in a buffer visiting a version-controlled file, the
+VC fileset is simply that one file. When you type them in a VC
+Directory buffer, and some files in it are marked, the VC fileset
+consists of the marked files (@pxref{VC Directory Mode}).
+
+ The principal VC command is an all-purpose command, @kbd{C-x v v}
+(@code{vc-next-action}), that performs either registration, locking,
+merging or a check-in (depending on the situation) on the current VC
+fileset. You can use @kbd{C-x v v} in a file-visiting buffer or in a
+VC Directory buffer.
+
+@table @kbd
+@itemx C-x v v
+Perform the appropriate next version control operation on the VC fileset.
+@end table
+
+@findex vc-next-action
+@kindex C-x v v
+ The precise action of @kbd{C-x v v} depends on the state of the VC
+fileset, and whether the version control system uses locking or
+merging. This is described in detail in the subsequent sections.
+
+ VC filesets are the way that VC mode bridges the gap between
+file-based and changeset-based version control systems. They are,
+essentially, a way to pass multiple file arguments as a group to
+version control commands. For example, on Subversion, a checkin with
+a multi-file VC fileset becomes a joint commit, as though you had
+typed @command{svn commit} with those file arguments at the shell
+command line. All files in a VC fileset must be under the same
+version control system; if they are not, Emacs signals an error when
+you attempt to execute a command on the fileset.
+
+ VC filesets are distinct from the ``named filesets'' used for
+viewing and visiting files in functional groups (@pxref{Filesets}).
+Unlike named filesets, VC filesets are not named and don't persist
+across sessions.
+
+@menu
+* VC With A Merging VCS:: Without locking: default mode for CVS.
+* VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS.
+* Advanced C-x v v:: Advanced features available with a prefix argument.
+@end menu
+
+@node VC With A Merging VCS
+@subsubsection Basic Version Control with Merging
+
+ When your version control system is merging-based (the default for
+CVS and all newer version control systems), work files are always
+writable; you need not do anything special to begin editing a file.
+The status indicator on the mode line is @samp{-} if the file is
+unmodified; it flips to @samp{:} as soon as you save any changes
+(@pxref{VC Mode Line}).
+
+ Here is what @kbd{C-x v v} does when using a merging-based system:
+
+@itemize @bullet
+@item
+If the work file is in a directory that is not controlled by any
+version control system, prompt for a repository type. Then, create a
+version control repository of that type and register the file with it.
+
+@item
+If the work file is in a directory that is controlled by a version
+control system but not registered with it, register the file.
+
+@item
+If the work file is the same as in the repository, do nothing.
+
+@item
+If you have not changed the work file, but some other user has checked
+in changes to the repository, merge those changes into the work file.
+
+@item
+If you have made modifications to the work file, attempt to commit
+the changes. To do this, Emacs first reads the log entry for the new
+revision (@pxref{Log Buffer}). If some other user has committed
+changes to the repository since you last checked it out, the checkin
+fails. In that case, type @kbd{C-x v v} again to merge those changes
+into your own work file; this puts the work file into a ``conflicted''
+state. Type @kbd{C-x v v} to clear the ``conflicted'' state; VC then
+regards the file as up-to-date and modified, and you can try to check
+it in again.
+
+To pick up any recent changes from the repository @emph{without}
+trying to commit your own changes, type @kbd{C-x v m @key{RET}}.
+@xref{Merging}.
+@end itemize
+
+ These rules also apply when you use RCS in its ``non-locking'' mode,
+except that changes are not automatically merged from the repository.
+Nothing informs you if another user has committed changes in the same
+file since you began editing it; when you commit your revision, his
+changes are removed (however, they remain in the repository and are
+thus not irrevocably lost). Therefore, you must verify that the
+current revision is unchanged before checking in your changes. In
+addition, locking is possible with RCS even in this mode: @kbd{C-x v
+v} with an unmodified file locks the file, just as it does with RCS in
+its normal locking mode (@pxref{VC With A Locking VCS}).
+
+@node VC With A Locking VCS
+@subsubsection Basic Version Control with Locking
+
+ Under a locking-based version control system (such as SCCS, and RCS
+in its default mode), @kbd{C-x v v} does the following:
+
+@itemize @bullet
+@item
+If the file is not locked, lock it and make it writable, so that you
+can change it.
+
+@item
+If the file is locked by you, and contains changes, commit the
+changes. In order to do this, Emacs first reads the log entry for the
+new revision. @xref{Log Buffer}.
+
+@item
+If the file is locked by you, but you have not changed it since you
+locked it, release the lock and makes the file read-only again.
+
+@item
+If the file is locked by some other user, ask whether you want to
+``steal the lock'' from that user. If you say yes, the file becomes
+locked by you, but a message is sent to the person who had formerly
+locked the file, to inform him of what has happened.
+@end itemize
+
+ These rules also apply when you use CVS in locking mode, except
+that CVS does not support stealing a lock.
+
+@node Advanced C-x v v
+@subsubsection Advanced Control in @kbd{C-x v v}
+
+@cindex revision ID in version control
+ When you give a prefix argument to @code{vc-next-action} (@kbd{C-u
+C-x v v}), it still performs the next logical version control
+operation, but accepts additional arguments to specify precisely how
+to do the operation.
+
+@itemize @bullet
+@item
+If the file is modified (or locked), you can specify the revision ID
+to use for the new version that you commit. This is one way to create
+a new branch (@pxref{Branches}).
+
+@item
+If the file is not modified (and unlocked), you can specify the
+revision to select; this lets you start working from an older
+revision, or on another branch. If you do not enter any revision,
+that takes you to the highest (``head'') revision on the current
+branch; therefore @kbd{C-u C-x v v @key{RET}} is a convenient way to
+get the latest version of a file from the repository.
+
+@item
+@cindex specific version control system
+Instead of the revision ID, you can also specify the name of a
+version control system. This is useful when one file is being managed
+with two version control systems at the same time
+@iftex
+(@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs
+Features}).
+@end iftex
+@ifnottex
+(@pxref{Local Version Control}).
+@end ifnottex
+
+@end itemize
+
+@node Log Buffer
+@subsection Features of the Log Entry Buffer
+
+ When you tell VC to commit a change, it pops up a buffer called
+@samp{*VC-Log*}. In this buffer, you should write a @dfn{log entry}
+describing the changes you have made (@pxref{Why Version Control?}).
+After you are done, type @kbd{C-c C-c}; this exits the buffer and
+commits the change, together with your log entry.
+
+ While in the @samp{*VC-Log*} buffer, you can write one or more
+@dfn{header lines}, specifying additional information to be supplied
+to the version control system. Each header line must occupy a single
+line at the top of the buffer; the first line that is not a header
+line is treated as the start of the log entry. For example, the
+following header line states that the present change was not written
+by you, but by another developer:
+
+@smallexample
+Author: J. R. Hacker <jrh@@example.com>
+@end smallexample
+
+@noindent
+Apart from the @samp{Author} header, Emacs recognizes the headers
+@samp{Date} (a manually-specified commit time) and @samp{Fixes} (a
+reference to a bug fixed by the change). Not all version control
+systems recognize all headers: Bazaar recognizes all three headers,
+while git, Mercurial, and Monotone recognizes only @samp{Author} and
+@samp{Summary}. If you specify a header for a version control that
+does not support it, the header is treated as part of the log entry.
+
+@findex log-edit-show-files
+@findex log-edit-show-diff
+ Type @kbd{C-c C-f} (@code{log-edit-show-files}) to display a list of
+files in the current VC fileset. If you called @kbd{C-x v v} directly
+from a work file, the fileset consists of that single file; if you
+called @kbd{C-x v v} from a VC directory buffer (@pxref{VC Directory
+Mode}), the fileset may consist of multiple files.
+
+@findex log-edit-insert-changelog
+ Type @kbd{C-c C-d} (@code{log-edit-show-diff}) to show a @dfn{diff}
+of the changes you have made (i.e., the differences between the work
+file and the repository revision from which you started editing).
+@xref{Old Revisions}.
+
+ If the current VC fileset includes one or more @file{ChangeLog}
+files (@pxref{Change Log}), type @kbd{C-c C-a}
+(@code{log-edit-insert-changelog}) to pull the relevant entries into
+the @samp{*VC-Log*} buffer. If the topmost item in each
+@file{ChangeLog} was made under your user name on the current date,
+this command searches that item for entries that match the file(s) to
+be committed; if found, these entries are inserted.
+@iftex
+@xref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features},
+@end iftex
+@ifnottex
+@xref{Change Logs and VC},
+@end ifnottex
+for the opposite way of working---generating ChangeLog entries from
+the revision control log.
+
+ To abort a check-in, just @strong{don't} type @kbd{C-c C-c} in that
+buffer. You can switch buffers and do other editing. As long as you
+don't try to commit another file, the entry you were editing remains
+in the @samp{*VC-Log*} buffer, and you can go back to that buffer at
+any time to complete the check-in.
+
+ If you change several source files for the same reason, it is often
+convenient to specify the same log entry for many of the files. (This
+is the normal way to do things on a changeset-oriented system, where
+comments are attached to changesets rather than the history of
+individual files.) The most convenient way to do this is to mark all
+the files in VC Directory Mode and commit from there; the log buffer
+will carry the fileset information with it and do a group commit when
+you type @kbd{C-c C-c}.
+
+ You can also browse the history of previous log entries to duplicate
+a checkin comment. This can be useful when you want several files to
+have checkin comments that vary only slightly from each other. The
+commands @kbd{M-n}, @kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this
+work just like the minibuffer history commands (except that these
+versions are used outside the minibuffer).
+
+@vindex vc-log-mode-hook
+ Each time you commit a change, the log entry buffer is put into VC
+Log Edit mode, which involves running two hooks: @code{text-mode-hook}
+and @code{vc-log-mode-hook}. @xref{Hooks}.
+
+@node Old Revisions
+@subsection Examining And Comparing Old Revisions
+
+ One of the convenient features of version control is the ability
+to examine any revision of a file, or compare two revisions.
+
+@table @kbd
+@item C-x v ~
+Prompt for a revision of the current file, and visit it in a buffer of
+its own (@code{vc-revision-other-window}).
+
+@item C-x v =
+Compare the files in the current fileset with the working revision(s)
+you started from (@code{vc-diff}). With a prefix argument, prompt for
+two revisions of the current fileset and compare them. You can call
+this command from a Dired buffer (@pxref{Dired}).
+
+@item C-x v D
+Compare the entire tree corresponding to the current fileset with the
+tree you started from (@code{vc-root-diff}). With a prefix argument,
+prompt for two revisions and compare their trees.
+
+@item C-x v g
+Display an annotated version of the file: for each line, show the
+latest revision in which it was modified (@code{vc-annotate}).
+@end table
+
+@findex vc-revision-other-window
+@kindex C-x v ~
+ To examine an old revision, visit the work file and type @kbd{C-x v
+~ @var{revision} @key{RET}} (@code{vc-revision-other-window}). Here,
+@var{revision} is either the desired revision ID (@pxref{VCS
+Concepts}), or the name of a tag or branch
+@iftex
+(@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}).
+@end iftex
+@ifnottex
+(@pxref{Tags}).
+@end ifnottex
+This command puts the text of the old revision in a file named
+@file{@var{filename}.~@var{revision}~}, and visits it in its own
+buffer in a separate window.
+
+@findex vc-diff
+@kindex C-x v =
+ @kbd{C-x v =} (@code{vc-diff}) compares each file in the current VC
+fileset (saving them if necessary) with the repository revision(s)
+from which you started editing. Note that the latter may or may not
+be the latest revision of the file(s).
+
+ The diff is displayed in another window, in a Diff mode buffer
+(@pxref{Diff Mode}) named @file{*vc-diff*}. In this buffer, the
+@kbd{g} (@code{revert-buffer}) command performs the file comparison
+again, generating a new diff.
+
+@findex vc-diff
+@kindex C-u C-x v =
+ To compare two arbitrary revisions of the current VC fileset, call
+@code{vc-diff} with a prefix argument: @kbd{C-u C-x v =}. This
+prompts for two revision IDs, using the minibuffer, and displays the
+diff in a special buffer in another window. Instead of providing a
+revision ID, you can give an empty input, which specifies the current
+contents of the work file; or a tag or branch name
+@iftex
+(@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}).
+@end iftex
+@ifnottex
+(@pxref{Tags}).
+@end ifnottex
+If your version control system is file-based (e.g. CVS) rather than
+changeset-based (Subversion, GNU Arch, git, Mercurial), supplying a
+revision ID for a multi-file fileset (as opposed to a symbolic tag
+name) is unlikely to return diffs that are connected in any meaningful
+way.
+
+ The command @kbd{C-x v D} (@code{vc-root-diff}) is similar to
+@kbd{C-x v =}, but it compares the entire tree associated with the
+current VC fileset with the tree you started with. This means all the
+files controlled by the current version control repository, even those
+that are not part of the current VC fileset.
+
+ If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a buffer that
+is neither visiting a version-controlled file nor a VC directory
+buffer, these commands generate a diff of all registered files in the
+current directory and its subdirectories.
+
+@findex vc-ediff
+The function @code{vc-ediff} works like @code{vc-diff} and provides a way to
+visually compare two revisions of a file in an Ediff session, @pxref{Top,
+Ediff, ediff, The Ediff Manual}. It compares the file associated with the
+current buffer with the last repository revision. To compare two arbitrary
+revisions of the current file, call @code{vc-ediff} with a prefix argument.
+
+@vindex vc-diff-switches
+@vindex vc-rcs-diff-switches
+ @kbd{C-x v =} works by running a variant of the @code{diff} utility
+designed to work with the version control system in use. The options
+to pass to the @code{diff} command are taken from the first non-@code{nil}
+value of @code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches},
+and @code{diff-switches} (@pxref{Comparing Files}), in that order.
+Since @code{nil} means to check the next variable in the sequence,
+either of the first two may use the value @code{t} to mean no switches at all.
+Most of the @samp{vc@dots{}diff-switches} variables default to
+@code{nil}, but some default to @code{t}. These are for those version
+control systems (e.g. SVN) whose @code{diff} implementations do not
+accept common options (e.g. @samp{-c}) likely to be in
+@code{diff-switches}.
+
+ The buffer produced by @kbd{C-x v =} supports the commands of
+Compilation mode (@pxref{Compilation Mode}), such as @kbd{C-x `} and
+@kbd{C-c C-c}, in both the ``old'' and ``new'' text, and they always
+find the corresponding locations in the current work file. (Older
+revisions are not, in general, present as files on your disk.)
+
+@findex vc-annotate
+@kindex C-x v g
+ For some back ends, you can display the file @dfn{annotated} with
+per-line revision information, by typing @kbd{C-x v g}
+(@code{vc-annotate}). This creates a new buffer (the ``annotate
+buffer'') displaying the file's text, with each part colored to show
+how old it is. Text colored red is new, blue means old, and
+intermediate colors indicate intermediate ages. By default, the color
+is scaled over the full range of ages, such that the oldest changes
+are blue, and the newest changes are red.
+
+ When you give a prefix argument to this command, Emacs reads two
+arguments using the minibuffer: the ID of which revision to display and
+annotate (instead of the current file contents), and the time span in
+days the color range should cover.
+
+ From the annotate buffer, these and other color scaling options are
+available from the @samp{VC-Annotate} menu. In this buffer, you can
+also use the following keys to browse the annotations of past revisions,
+view diffs, or view log entries:
+
+@table @kbd
+@item p
+Annotate the previous revision, that is to say, the revision before
+the one currently annotated. A numeric prefix argument is a repeat
+count, so @kbd{C-u 10 p} would take you back 10 revisions.
+
+@item n
+Annotate the next revision---the one after the revision currently
+annotated. A numeric prefix argument is a repeat count.
+
+@item j
+Annotate the revision indicated by the current line.
+
+@item a
+Annotate the revision before the one indicated by the current line.
+This is useful to see the state the file was in before the change on
+the current line was made.
+
+@item f
+Show in a buffer the file revision indicated by the current line.
+
+@item d
+Display the diff between the current line's revision and the previous
+revision. This is useful to see what the current line's revision
+actually changed in the file.
+
+@item D
+Display the diff between the current line's revision and the previous
+revision for all files in the changeset (for VC systems that support
+changesets). This is useful to see what the current line's revision
+actually changed in the tree.
+
+@item l
+Show the log of the current line's revision. This is useful to see
+the author's description of the changes in the revision on the current
+line.
+
+@item w
+Annotate the working revision--the one you are editing. If you used
+@kbd{p} and @kbd{n} to browse to other revisions, use this key to
+return to your working revision.
+
+@item v
+Toggle the annotation visibility. This is useful for looking just at
+the file contents without distraction from the annotations.
+@end table
+
+@node Secondary VC Commands
+@subsection The Secondary Commands of VC
+
+ This section explains the secondary commands of VC.
+
+@menu
+* Registering:: Putting a file under version control.
+* VC Change Log:: Viewing the VC Change Log.
+* VC Undo:: Canceling changes before or after check-in.
+@end menu
+
+@node Registering
+@subsubsection Registering a File for Version Control
+
+@kindex C-x v i
+@findex vc-register
+ You can put any file under version control by simply visiting it, and
+then typing @w{@kbd{C-x v i}} (@code{vc-register}).
+
+@table @kbd
+@item C-x v i
+Register the visited file for version control.
+@end table
+
+ To register the file, Emacs must choose which version control system
+to use for it. If the file's directory already contains files
+registered in a version control system, Emacs uses that system. If
+there is more than one system in use for a directory, Emacs uses the
+one that appears first in @code{vc-handled-backends}
+@iftex
+(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
+@end iftex
+@ifnottex
+(@pxref{Customizing VC}).
+@end ifnottex
+On the other hand, if there are no files already registered, Emacs uses
+the first system from @code{vc-handled-backends} that could register
+the file (for example, you cannot register a file under CVS if its
+directory is not already part of a CVS tree); with the default value
+of @code{vc-handled-backends}, this means that Emacs uses RCS in this
+situation.
+
+ If locking is in use, @kbd{C-x v i} leaves the file unlocked and
+read-only. Type @kbd{C-x v v} if you wish to start editing it. After
+registering a file with CVS, you must subsequently commit the initial
+revision by typing @kbd{C-x v v}. Until you do that, the revision ID
+appears as @samp{@@@@} in the mode line.
+
+@vindex vc-default-init-revision
+@cindex initial revision ID to register
+ The default initial revision ID for a newly registered file
+varies by what VCS you are using; normally it will be 1.1 on VCSes
+that use dot-pair revision IDs and 1 on VCSes that use monotonic IDs.
+You can specify a different default by setting the variable
+@code{vc-default-init-revision}, or you can give @kbd{C-x v i} a
+numeric argument; then it reads the initial revision ID for this
+particular file using the minibuffer.
+
+@vindex vc-initial-comment
+ If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an
+initial comment to describe the purpose of this source file. Reading
+the initial comment works like reading a log entry (@pxref{Log Buffer}).
+
+@node VC Change Log
+@subsubsection VC Change Log
+
+@table @kbd
+@item C-x v l
+Display revision control state and change history
+(@code{vc-print-log}).
+
+@item C-x v L
+Display the change history for the current repository
+(@code{vc-print-root-log}).
+
+@item C-x v I
+Display the changes that will be received with a pull operation
+(@code{vc-log-incoming}).
+
+@item C-x v O
+Display the changes that will be sent by the next push operation
+(@code{vc-log-outgoing}).
+@end table
+
+@kindex C-x v l
+@findex vc-print-log
+ The command @kbd{C-x v l} (@code{vc-print-log}) displays a buffer
+named @samp{*vc-change-log*} in a new window. This buffer lists the
+changes to the current file, including the associated log entries.
+(These are the log entries associated with the version control system,
+i.e. the ones you enter via the @samp{*VC-Log*} buffer. @xref{Log
+Buffer}.) Point is centered at the revision of the file currently
+being visited. With a prefix argument, the command prompts for the
+revision to center on, and the maximum number of revisions to display.
+You can call this command from a Dired buffer (@pxref{Dired}).
+
+@findex vc-print-root-log
+ Type @kbd{C-x v L} (@code{vc-print-root-log}) to display a
+@samp{*vc-change-log*} buffer showing the history of the
+version-controlled directory tree as a whole. With a prefix argument,
+the command prompts for the maximum number of revisions to display.
+RCS, SCCS, and CVS do not support this feature.
+
+ On a distributed version control system, the @kbd{C-x v I}
+(@code{vc-log-incoming}) command displays a log buffer showing the
+changes that will be applied, the next time you run the version
+control system's ``pull'' command to get new revisions from another
+repository. This other repository is the default one from which
+changes are pulled, as defined by the version control system; with a
+prefix argument, @code{vc-log-incoming} prompts for a specific
+repository from which changes would be pulled, and lists the changes
+accordingly. Similarly, @kbd{C-x v O} (@code{vc-log-outgoing}) shows
+the changes that will be sent to another repository, the next time you
+run the ``push'' command; with a prefix argument, it prompts for a
+specific repository to which changes would be pushed.
+
+ In the @samp{*vc-change-log*} buffer, you can use the following keys
+to move between the logs of revisions and of files, to view past
+revisions, to modify change comments, to view annotations and to view
+diffs:
+
+@table @kbd
+@item p
+Move to the previous revision-item in the buffer. (Revision entries in the log
+buffer are usually in reverse-chronological order, so the previous
+revision-item usually corresponds to a newer revision.) A numeric
+prefix argument is a repeat count.
+
+@item n
+Move to the next revision-item (which most often corresponds to the
+previous revision of the file). A numeric prefix argument is a repeat
+count.
+
+@item P
+Move to the log of the previous file, when the logs of multiple files
+are in the log buffer (@pxref{VC Directory Mode}). Otherwise, just
+move to the beginning of the log. A numeric prefix argument is a
+repeat count, so @kbd{C-u 10 P} would move backward 10 files.
+
+@item N
+Move to the log of the next file, when the logs of multiple files are
+in the log buffer (@pxref{VC Directory Mode}). It also takes a
+numeric prefix argument as a repeat count.
+
+@item a
+Annotate the revision indicated by the current line.
+
+@item e
+Modify the change comment displayed at point. Note that not all VC
+systems support modifying change comments.
+
+@item f
+Visit the revision indicated at the current line, like typing @kbd{C-x
+v ~} and specifying this revision's ID (@pxref{Old Revisions}).
+
+@item d
+Display the diff (@pxref{Comparing Files}) between the revision
+indicated at the current line and the next earlier revision. This is
+useful to see what actually changed in the file when the revision
+indicated on the current line was committed.
+
+@item D
+Display the changeset diff (@pxref{Comparing Files}) between the
+revision indicated at the current line and the next earlier revision.
+This is useful to see all the changes to all files that the revision
+indicated on the current line did when it was committed.
+@end table
+
+@vindex vc-log-show-limit
+Because fetching many log entries can be slow, the
+@samp{*vc-change-log*} buffer displays no more than 2000 revisions by
+default. The variable @code{vc-log-show-limit} specifies this limit;
+if you set the value to zero, that removes the limit. You can also
+increase the number of revisions shown in an existing
+@samp{*vc-change-log*} buffer by clicking on the @samp{Show 2X
+entries} or @samp{Show unlimited entries} buttons at the end of the
+buffer. However, RCS, SCCS, and CVS do not support this feature.
+
+@node VC Undo
+@subsubsection Undoing Version Control Actions
+
+@table @kbd
+@item C-x v u
+Revert the buffer and the file to the working revision from which you started
+editing the file.
+
+@item C-x v c
+Remove the last-entered change from the master for the visited file.
+This undoes your last check-in.
+@end table
+
+@kindex C-x v u
+@findex vc-revert-buffer
+ If you want to discard your current set of changes and revert to the
+working revision from which you started editing the file, use @kbd{C-x
+v u} (@code{vc-revert-buffer}). If the version control system is
+locking-based, this leaves the file unlocked, and you must lock it
+again before making new changes. @kbd{C-x v u} requires confirmation,
+unless it sees that you haven't made any changes with respect to the
+master copy of the working revision.
+
+ @kbd{C-x v u} is also the command to unlock a file if you lock it and
+then decide not to change it.
+
+@kindex C-x v c
+@findex vc-rollback
+ To cancel a change that you already committed, use @kbd{C-x v c}
+(@code{vc-rollback}). This command discards all record of the most
+recent checked-in revision, but only if your work file corresponds to
+that revision---you cannot use @kbd{C-x v c} to cancel a revision that
+is not the latest on its branch. Note that many version control
+systems do not support rollback at all; this command is something of a
+historical relic.
+
+@node VC Directory Mode
+@subsection VC Directory Mode
+
+@kindex C-x v d
+@findex vc-dir
+ When you are working on a large program, it is often useful to find
+out which files have changed within an entire directory tree, or to
+view the status of all files under version control at once, and to
+perform version control operations on collections of files. You can
+use the command @kbd{C-x v d} (@code{vc-dir}) to make a directory
+listing that includes only files relevant for version control. This
+creates a @dfn{VC Directory buffer} and displays it in a separate
+window.
+
+@cindex PCL-CVS
+@pindex cvs
+@cindex CVS directory mode
+ The VC Directory buffer works with all the version control systems
+that VC supports. For CVS, Emacs also offers a more powerful facility
+called PCL-CVS. @xref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The
+Emacs Front-End to CVS}.
+
+@menu
+* Buffer: VC Directory Buffer. What the buffer looks like and means.
+* Commands: VC Directory Commands. Commands to use in a VC directory buffer.
+@end menu
+
+@node VC Directory Buffer
+@subsubsection The VC Directory Buffer
+
+ The VC Directory buffer contains a list of version-controlled files
+in the current directory and its subdirectories. Files which are
+up-to-date (have no local differences from the repository copy) are
+usually hidden; if all files in a subdirectory are up-to-date, the
+subdirectory is hidden as well. There is an exception to this rule:
+if VC mode detects that a file has changed to an up-to-date state
+since you last looked at it, that file and its state are shown.
+
+ If a directory uses more that one version control system, you can
+select which system to use for the @code{vc-dir} command by invoking
+@code{vc-dir} with a prefix argument: @kbd{C-u C-x v d}.
+
+ The line for an individual file shows the version control state of
+the file. Under RCS and SCCS, the name of the user locking the file
+is shown; under CVS, an abbreviated version of the @samp{cvs status}
+output is used. Here is an example using CVS:
+
+@smallexample
+@group
+ ./
+ modified file1.c
+ needs-update file2.c
+ needs-merge file3.c
+@end group
+@end smallexample
+
+@noindent
+In this example, @samp{file1.c} is modified with respect to the
+repository, and @samp{file2.c} is not. @samp{file3.c} is modified,
+but other changes have also been committed---you need to merge them
+with the work file before you can check it in.
+
+@vindex vc-stay-local
+@vindex vc-cvs-stay-local
+ In the above, if the repository were on a remote machine, VC only
+contacts it when the variable @code{vc-stay-local} (or
+@code{vc-cvs-stay-local}) is @code{nil}
+@iftex
+(@pxref{CVS Options,,,emacs-xtra, Specialized Emacs Features}).
+@end iftex
+@ifnottex
+(@pxref{CVS Options}).
+@end ifnottex
+This is because access to the repository may be slow, or you may be
+working offline and not have access to the repository at all. As a
+consequence, VC would not be able to tell you that @samp{file3.c} is
+in the ``merge'' state; you would learn that only when you try to
+check-in your modified copy of the file, or use a command such as
+@kbd{C-x v m}.
+
+ In practice, this is not a problem because CVS handles this case
+consistently whenever it arises. In VC, you'll simply get prompted to
+merge the remote changes into your work file first. The benefits of
+less network communication usually outweigh the disadvantage of not
+seeing remote changes immediately.
+
+@vindex vc-directory-exclusion-list
+ When a VC directory displays subdirectories it omits some that
+should never contain any files under version control. By default,
+this includes Version Control subdirectories such as @samp{RCS} and
+@samp{CVS}; you can customize this by setting the variable
+@code{vc-directory-exclusion-list}.
+
+@node VC Directory Commands
+@subsubsection VC Directory Commands
+
+ VC Directory mode has a full set of navigation and marking commands
+for picking out filesets. Some of these are also available in a
+context menu invoked by @kbd{mouse-2}.
+
+ Up- and down-arrow keys move in the buffer; @kbd{n} and @kbd{p} also
+move vertically as in other list-browsing modes. @key{SPC} and
+@key{TAB} behave like down-arrow, and @key{BackTab} behaves like
+up-arrow.
+
+ Both @kbd{C-m} and @kbd{f} visit the file on the current
+line. @kbd{o} visits that file in another window. @kbd{q} dismisses
+the directory buffer.
+
+ @kbd{x} hides up-to-date files.
+
+ @kbd{m} marks the file or directory on the current line. If the
+region is active, @kbd{m} marks all the files in the region. There
+are some restrictions when marking: a file cannot be marked if any of
+its parent directories are marked, and a directory cannot be marked if
+any files in it or in its child directories are marked.
+
+ @kbd{M} marks all the files with the same VC state as the current
+file if the cursor is on a file. If the cursor is on a directory, it
+marks all child files. With a prefix argument: marks all files and
+directories.
+
+ @kbd{u} unmarks the file or directory on the current line. If the
+region is active, it unmarks all the files in the region.
+
+ @kbd{U} marks all the files with the same VC state as the current file
+if the cursor is on a file. If the cursor is on a directory, it
+unmarks all child files. With a prefix argument: unmarks all marked
+files and directories.
+
+ It is possible to do search, search and replace, incremental search,
+and incremental regexp search on multiple files. These commands will
+work on all the marked files or the current file if nothing is marked.
+If a directory is marked, the files in that directory shown in the VC
+directory buffer will be used.
+
+ @kbd{S} searches the marked files.
+
+ @kbd{Q} does a query replace on the marked files.
+
+ @kbd{M-s a C-s} does an incremental search on the marked files.
+
+ @kbd{M-s a C-M-s} does an incremental regular expression search
+on the marked files.
+
+@cindex stashes in version control
+@cindex shelves in version control
+ Commands are also accessible from the VC-dir menu. Note that some
+VC backends use the VC-dir menu to make available extra,
+backend-specific, commands. For example, Git and Bazaar allow you to
+manipulate @dfn{stashes} and @dfn{shelves}. (These provide a
+mechanism to temporarily store uncommitted changes somewhere out of
+the way, and bring them back at a later time.)
+
+ Normal VC commands with the @kbd{C-x v} prefix work in VC directory
+buffers. Some single-key shortcuts are available as well; @kbd{=},
+@kbd{+}, @kbd{l}, @kbd{i}, and @kbd{v} behave as through prefixed with
+@kbd{C-x v}.
+
+ The command @kbd{C-x v v} (@code{vc-next-action}) operates on all
+the marked files, so that you can commit several files at once. If
+the underlying VC supports atomic commits of multiple-file changesets,
+@kbd{C-x v v} with a selected set of modified but not committed files
+will commit all of them at once as a single changeset.
+
+ When @kbd{C-x v v} (@code{vc-next-action}) operates on multiple
+files, all of those files must be either in the same state or in
+compatible states (added, modified and removed states are considered
+compatible). Otherwise it signals an error. This differs from the
+behavior of older versions of VC, which did not have fileset
+operations and simply did @code{vc-next-action} on each file
+individually.
+
+ If any files are in a state that calls for commit, @kbd{C-x v v} reads a
+single log entry and uses it for the changeset as a whole. If the
+underling VCS is file- rather than changeset-oriented, the log entry
+will be replicated into the history of each file.
+
+@node Branches
+@subsection Multiple Branches of a File
+@cindex branch (version control)
+@cindex trunk (version control)
+
+ One use of version control is to maintain multiple ``current''
+revisions of a file. For example, you might have different revisions of a
+program in which you are gradually adding various unfinished new
+features. Each such independent line of development is called a
+@dfn{branch}. VC allows you to create branches, switch between
+different branches, and merge changes from one branch to another.
+Please note, however, that branches are not supported for SCCS.
+
+ A file's main line of development is usually called the @dfn{trunk}.
+You can create multiple branches from the trunk. How the difference
+between trunk and branch is made visible is dependent on whether the
+VCS uses dot-pair or monotonic version IDs.
+
+ In VCSes with dot-pair revision IDs, the revisions on the trunk are
+normally IDed 1.1, 1.2, 1.3, etc. At any such revision, you can
+start an independent branch. A branch starting at revision 1.2 would
+have revision ID 1.2.1.1, and consecutive revisions on this branch
+would have IDs 1.2.1.2, 1.2.1.3, 1.2.1.4, and so on. If there is
+a second branch also starting at revision 1.2, it would consist of
+revisions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc.
+
+ In VCSes with monotonic revision IDs, trunk revisions are IDed as
+1, 2, 3, etc. A branch from (say) revision 2 might start with 2.1 and
+continue through 2.2, 2.3, etc. But naming conventions for branches
+and subbranches vary widely on these systems, and some (like
+Mercurial) never depart from the monotonic integer sequence at all.
+Consult the documentation of the VCS you are using.
+
+@cindex head revision
+ If you omit the final component of a dot-pair revision ID, that is called a
+@dfn{branch ID}. It refers to the highest existing revision on that
+branch---the @dfn{head revision} of that branch. The branches in the
+dot-pair example above have branch IDs 1.2.1 and 1.2.2.
+
+@menu
+* Switching Branches:: How to get to another existing branch.
+* Creating Branches:: How to start a new branch.
+* Merging:: Transferring changes between branches.
+* Multi-User Branching:: Multiple users working at multiple branches
+ in parallel.
+@end menu
+
+@node Switching Branches
+@subsubsection Switching between Branches
+
+ To switch between branches, type @kbd{C-u C-x v v} and specify the
+revision ID you want to select. On a locking-based system, this
+version is then visited @emph{unlocked} (write-protected), so you can
+examine it before locking it. Switching branches in this way is allowed
+only when the file is not locked.
+
+ On a VCS with dot-pair IDs, you can omit the minor part, thus giving
+only the branch ID; this takes you to the head version on the
+chosen branch. If you only type @key{RET}, Emacs goes to the highest
+version on the trunk.
+
+ After you have switched to any branch (including the main branch), you
+stay on it for subsequent VC commands, until you explicitly select some
+other branch.
+
+@node Creating Branches
+@subsubsection Creating New Branches
+
+ To create a new branch from a head revision (one that is the latest
+in the branch that contains it), first select that revision if
+necessary, lock it with @kbd{C-x v v}, and make whatever changes you
+want. Then, when you commit the changes, use @kbd{C-u C-x v v}. This
+lets you specify the revision ID for the new revision. You should
+specify a suitable branch ID for a branch starting at the current
+revision. For example, if the current revision is 2.5, the branch ID
+should be 2.5.1, 2.5.2, and so on, depending on the number of existing
+branches at that point.
+
+ To create a new branch at an older revision (one that is no longer the
+head of a branch), first select that revision (@pxref{Switching
+Branches}). Your procedure will then differ depending on whether you
+are using a locking or merging-based VCS.
+
+ On a locking VCS, you will need to lock the old revision branch with
+@kbd{C-x v v}. You'll be asked to confirm, when you lock the old
+revision, that you really mean to create a new branch---if you say no,
+you'll be offered a chance to lock the latest revision instead. On
+a merging-based VCS you will skip this step.
+
+ Then make your changes and type @kbd{C-x v v} again to commit a new
+revision. This automatically creates a new branch starting from the
+selected revision. You need not specially request a new branch,
+because that's the only way to add a new revision at a point that is
+not the head of a branch.
+
+ After the branch is created, you ``stay'' on it. That means that
+subsequent check-ins create new revisions on that branch. To leave the
+branch, you must explicitly select a different revision with @kbd{C-u C-x
+v v}. To transfer changes from one branch to another, use the merge
+command, described in the next section.
+
+@node Merging
+@subsubsection Merging Branches
+
+@cindex merging changes
+ When you have finished the changes on a certain branch, you will
+often want to incorporate them into the file's main line of development
+(the trunk). This is not a trivial operation, because development might
+also have proceeded on the trunk, so that you must @dfn{merge} the
+changes into a file that has already been changed otherwise. VC allows
+you to do this (and other things) with the @code{vc-merge} command.
+
+@table @kbd
+@item C-x v m (vc-merge)
+Merge changes into the work file.
+@end table
+
+@kindex C-x v m
+@findex vc-merge
+ @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it
+into the current version of the work file. It firsts asks you in the
+minibuffer where the changes should come from. If you just type
+@key{RET}, Emacs merges any changes that were made on the same branch
+since you checked the file out (we call this @dfn{merging the news}).
+This is the common way to pick up recent changes from the repository,
+regardless of whether you have already changed the file yourself.
+
+ You can also enter a branch ID or a pair of revision IDs in
+the minibuffer. Then @kbd{C-x v m} finds the changes from that
+branch, or the differences between the two revisions you specified, and
+merges them into the current revision of the current file.
+
+ As an example, suppose that you have finished a certain feature on
+branch 1.3.1. In the meantime, development on the trunk has proceeded
+to revision 1.5. To merge the changes from the branch to the trunk,
+first go to the head revision of the trunk, by typing @kbd{C-u C-x v v
+@key{RET}}. Revision 1.5 is now current. If locking is used for the file,
+type @kbd{C-x v v} to lock revision 1.5 so that you can change it. Next,
+type @kbd{C-x v m 1.3.1 @key{RET}}. This takes the entire set of changes on
+branch 1.3.1 (relative to revision 1.3, where the branch started, up to
+the last revision on the branch) and merges it into the current revision
+of the work file. You can now commit the changed file, thus creating
+revision 1.6 containing the changes from the branch.
+
+ It is possible to do further editing after merging the branch, before
+the next check-in. But it is usually wiser to commit the merged
+revision, then lock it and make the further changes. This will keep
+a better record of the history of changes.
+
+@cindex conflicts
+@cindex resolving conflicts
+ When you merge changes into a file that has itself been modified, the
+changes might overlap. We call this situation a @dfn{conflict}, and
+reconciling the conflicting changes is called @dfn{resolving a
+conflict}.
+
+ Whenever conflicts occur during merging, VC detects them, tells you
+about them in the echo area, and asks whether you want help in merging.
+If you say yes, it starts an Ediff session (@pxref{Top,
+Ediff, Ediff, ediff, The Ediff Manual}).
+
+ If you say no, the conflicting changes are both inserted into the
+file, surrounded by @dfn{conflict markers}. The example below shows how
+a conflict region looks; the file is called @samp{name} and the current
+master file revision with user B's changes in it is 1.11.
+
+@c @w here is so CVS won't think this is a conflict.
+@smallexample
+@group
+@w{<}<<<<<< name
+ @var{User A's version}
+=======
+ @var{User B's version}
+@w{>}>>>>>> 1.11
+@end group
+@end smallexample
+
+@findex vc-resolve-conflicts
+ Then you can resolve the conflicts by editing the file manually. Or
+you can type @code{M-x vc-resolve-conflicts} after visiting the file.
+This starts an Ediff session, as described above. Don't forget to
+commit the merged version afterwards.
+
+@findex vc-find-conflicted-file
+ If there is more than one conflicted file in a merge, type @kbd{M-x
+vc-find-conflicted-file} after resolving the conflicts in each file.
+This command visits the next conflicted file, and moves point to the
+first conflict marker in that file.
+
+@node Multi-User Branching
+@subsubsection Multi-User Branching
+
+ It is often useful for multiple developers to work simultaneously on
+different branches of a file. CVS and later systems allow this by
+default; for RCS, it is possible if you create multiple source
+directories. Each source directory should have a link named
+@file{RCS} which points to a common directory of RCS master files.
+Then each source directory can have its own choice of selected
+revisions, but all share the same common RCS records.
+
+ This technique works reliably and automatically, provided that the
+source files contain RCS version headers
+@iftex
+(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}).
+@end iftex
+@ifnottex
+(@pxref{Version Headers}).
+@end ifnottex
+The headers enable Emacs to be sure, at all times, which revision
+ID is present in the work file.
+
+ If the files do not have version headers, you must instead tell Emacs
+explicitly in each session which branch you are working on. To do this,
+first find the file, then type @kbd{C-u C-x v v} and specify the correct
+branch ID. This ensures that Emacs knows which branch it is using
+during this particular editing session.
+
+@ifnottex
+@include vc1-xtra.texi
+@end ifnottex
+
@node Change Log
@section Change Logs
+@cindex change log
A change log file contains a chronological record of when and why you
have changed a program, consisting of a sequence of entries describing
individual changes. Normally it is kept in a file called
record changes for all the files in its directory and all its
subdirectories.
-@cindex change log
+@menu
+* Change Log Commands:: Commands for editing change log files.
+* Format of ChangeLog:: What the change log file looks like.
+@end menu
+
+@node Change Log Commands
+@subsection Change Log Commands
+
@kindex C-x 4 a
@findex add-change-log-entry-other-window
The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file
rather than starting a new item.
+You can combine multiple changes of the same nature. If you don't
+enter any text after the initial @kbd{C-x 4 a}, any subsequent
+@kbd{C-x 4 a} adds another symbol to the change.
+
@vindex add-log-always-start-new-record
If @code{add-log-always-start-new-record} is non-@code{nil},
@kbd{C-x 4 a} always makes a new entry, even if the last entry
@kbd{C-j} and auto-fill indent each new line like the previous line;
this is convenient for entering the contents of an entry.
+You can use the @code{next-error} command (by default bound to
+@kbd{C-x `}) to move between entries in the Change Log, when Change
+Log mode is on. You will jump to the actual site in the file that was
+changed, not just to the next Change Log entry. You can also use
+@code{previous-error} to move back in the same list.
+
@findex change-log-merge
You can use the command @kbd{M-x change-log-merge} to merge other
log files into a buffer in Change Log Mode, preserving the date
ordering of entries.
- Version control systems are another way to keep track of changes in your
-program and keep a change log. @xref{Log Buffer}.
+ Version control systems are another way to keep track of changes in
+your program and keep a change log. In the VC log buffer, typing
+@kbd{C-c C-a} (@code{log-edit-insert-changelog}) inserts the relevant
+Change Log entry, if one exists (@pxref{Log Buffer}). You can also
+insert a VC log entry into a Change Log buffer by typing @kbd{C-x v a}
+(@code{vc-update-change-log}) in the Change Log buffer
+@iftex
+(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
+@end iftex
+@ifnottex
+(@pxref{Change Logs and VC}).
+@end ifnottex
@node Format of ChangeLog
-@section Format of ChangeLog
+@subsection Format of ChangeLog
- A change log entry starts with a header line that contains the current
-date, your name, and your email address (taken from the variable
-@code{add-log-mailing-address}). Aside from these header lines, every
-line in the change log starts with a space or a tab. The bulk of the
-entry consists of @dfn{items}, each of which starts with a line starting
-with whitespace and a star. Here are two entries, both dated in May
-1993, with two items and one item respectively.
+ A change log entry starts with a header line that contains the
+current date, your name (taken from the variable
+@code{add-log-full-name}), and your email address (taken from the
+variable @code{add-log-mailing-address}). Aside from these header
+lines, every line in the change log starts with a space or a tab. The
+bulk of the entry consists of @dfn{items}, each of which starts with a
+line starting with whitespace and a star. Here are two entries, both
+dated in May 1993, with two items and one item respectively.
@iftex
@medbreak
@section Tags Tables
@cindex tags and tag tables
- A @dfn{tags table} is a description of how a multi-file program is
-broken up into files. It lists the names of the component files and the
-names and positions of the functions (or other named subunits) in each
-file. Grouping the related files makes it possible to search or replace
-through all the files with one command. Recording the function names
-and positions makes possible the @kbd{M-.} command which finds the
-definition of a function by looking up which of the files it is in.
-
- Tags tables are stored in files called @dfn{tags table files}. The
-conventional name for a tags table file is @file{TAGS}.
-
- Each entry in the tags table records the name of one tag, the name of the
-file that the tag is defined in (implicitly), and the position in that
-file of the tag's definition. When a file parsed by @code{etags} is
-generated from a different source file, like a C file generated from a
-Cweb source file, the tags of the parsed file reference the source
-file.
-
- Just what names from the described files are recorded in the tags table
-depends on the programming language of the described file. They
-normally include all file names, functions and subroutines, and may
-also include global variables, data types, and anything else
-convenient. Each name recorded is called a @dfn{tag}.
+ A @dfn{tag} is a reference to a subunit in a program or in a
+document. In program source code, tags reference syntactic elements
+of the program: functions, subroutines, data types, macros, etc. In a
+document, tags reference chapters, sections, appendices, etc. Each
+tag specifies the name of the file where the corresponding subunit is
+defined, and the position of the subunit's definition in that file.
+
+ A @dfn{tags table} records the tags extracted by scanning the source
+code of a certain program or a certain document. Tags extracted from
+generated files reference the original files, rather than the
+generated files that were scanned during tag extraction. Examples of
+generated files include C files generated from Cweb source files, from
+a Yacc parser, or from Lex scanner definitions; @file{.i} preprocessed
+C files; and Fortran files produced by preprocessing @file{.fpp}
+source files.
+
+ To produce a tags table, you use the @samp{etags} command,
+submitting it a document or the source code of a program.
+@samp{etags} writes the tags to a @dfn{tags table file}, or @dfn{tags
+file} in short. The conventional name for a tags file is @file{TAGS}.
+
+ Emacs uses the information recorded in tags tables in commands that
+search or replace through multiple source files: these commands use
+the names of the source files recorded in the tags table to know which
+files to search. Other commands, such as @kbd{M-.}, which finds the
+definition of a function, use the recorded information about the
+function names and positions to find the source file and the position
+within that file where the function is defined.
@cindex C++ class browser, tags
@cindex tags, C++
@xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}.
@menu
-* Tag Syntax:: Tag syntax for various types of code and text files.
-* Create Tags Table:: Creating a tags table with @code{etags}.
+* Tag Syntax:: Tag syntax for various types of code and text files.
+* Create Tags Table:: Creating a tags table with @code{etags}.
* Etags Regexps:: Create arbitrary tags using regular expressions.
-* Select Tags Table:: How to visit a tags table.
-* Find Tag:: Commands to find the definition of a specific tag.
-* Tags Search:: Using a tags table for searching and replacing.
-* List Tags:: Listing and finding tags defined in a file.
+* Select Tags Table:: How to visit a tags table.
+* Find Tag:: Commands to find the definition of a specific tag.
+* Tags Search:: Using a tags table for searching and replacing.
+* List Tags:: Listing and finding tags defined in a file.
@end menu
@node Tag Syntax
You can also use the collection of tag names to complete a symbol
name in the buffer. @xref{Symbol Completion}.
+ You can use @kbd{M-x next-file} to visit the files in the selected
+tags table. The first time this command is called, it visits the
+first file in the tags table. Each subsequent call visits the next
+file in the table, unless a prefix argument is supplied, in which case
+it returns to the first file.
+
+@node EDE
+@section Emacs Development Environment
+@cindex EDE (Emacs Development Environment)
+@cindex Emacs Development Environment
+@cindex Integrated development environment
+
+EDE (@dfn{Emacs Development Environment}) is a package that simplifies
+the task of creating, building, and debugging large programs with
+Emacs. It provides some of the features of an IDE, or @dfn{Integrated
+Development Environment}, in Emacs.
+
+This section provides a brief description of EDE usage.
@ifnottex
-@include emerge-xtra.texi
+For full details, see @ref{Top, EDE,, ede, Emacs Development Environment}.
@end ifnottex
+@iftex
+For full details on Ede, type @kbd{C-h i} and then select the EDE
+manual.
+@end iftex
-@ignore
- arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb
-@end ignore
+ EDE is implemented as a global minor mode (@pxref{Minor Modes}). To
+enable it, type @kbd{M-x global-ede-mode} or click on the
+@samp{Project Support (EDE)} item in the @samp{Tools} menu. You can
+also enable EDE each time you start Emacs, by adding the following
+line to your initialization file:
+
+@smallexample
+(global-ede-mode t)
+@end smallexample
+
+@noindent
+Activating EDE adds a menu named @samp{Development} to the menu bar.
+Many EDE commands, including the ones described below, can be invoked
+from this menu.
+
+ EDE organizes files into @dfn{projects}, which correspond to
+directory trees. The @dfn{project root} is the topmost directory of a
+project. To define a new project, visit a file in the desired project
+root and type @kbd{M-x ede-new}. This command prompts for a
+@dfn{project type}, which refers to the underlying method that EDE
+will use to manage the project (@pxref{Creating a Project, EDE,, ede,
+Emacs Development Environment}). The most common project types are
+@samp{Make}, which uses Makefiles, and @samp{Automake}, which uses GNU
+Automake (@pxref{Top, Automake,, automake, Automake}). In both cases,
+EDE also creates a file named @file{Project.ede}, which stores
+information about the project.
+
+ A project may contain one or more @dfn{targets}. A target can be an
+object file, executable program, or some other type of file, which is
+``built'' from one or more of the files in the project.
+
+ To add a new @dfn{target} to a project, type @kbd{C-c . t}
+(@code{M-x ede-new-target}). This command also asks if you wish to
+``add'' the current file to that target, which means that the target
+is to be built from that file. After you have defined a target, you
+can add more files to it by typing @kbd{C-c . a}
+(@code{ede-add-file}).
+
+ To build a target, type @kbd{C-c . c} (@code{ede-compile-target}).
+To build all the targets in the project, type @kbd{C-c . C}
+(@code{ede-compile-project}). EDE uses the file types to guess how
+the target should be built.
+
+@ifnottex
+@include emerge-xtra.texi
+@end ifnottex