@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 Free Software Foundation, Inc.
+@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
+@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
+* Version Control:: Using version control systems.
* Change Log:: Maintaining a change history for your program.
-* Format of ChangeLog:: What the change log file looks like.
-* Tags:: Go direct to any function in your program in one
+* Tags:: Go directly to any function in your program in one
command. Tags remembers which file it is in.
@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 package that can record multiple
+versions of a source file, storing information such as the creation
+time of each version, who created it, and a description of what was
+changed in that version.
+
+ The Emacs version control interface is called VC. Its 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, GNU Arch, RCS,
+and Bazaar.
+
+ VC is enabled automatically whenever you visit a file that is
+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.
+* 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.
+Though VC cannot completely bridge the gaps between version control
+systems with widely differing capabilities, it does provide a uniform
+interface to many version control operations. Regardless of which
+version control system is in use, you will be able to do basic
+operations in much the same way.
+
+ 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.
+* 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 or
+@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. Almost everything you can do with RCS can be done through VC.
+However, you cannot use RCS over the network, and it only works at the
+level of individual files rather than projects.
+
+@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. It lacks
+support for atomic commits or file moving/renaming. VC supports all
+basic editing operations under CVS. For some less common tasks, you
+still need to call CVS from the command line. Note also that before
+using CVS you must set up a repository, which is a subject too complex
+to treat here.
+
+@cindex SVN
+@cindex Subversion
+@item
+Subversion (SVN) is a free version control system designed to be
+similar to CVS but without its problems. 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 a version control system designed for distributed work.
+It differs in many ways from older systems like CVS and RCS. It
+provides different methods for interoperating between users, support
+for offline operations, and good branching and merging features. It
+also supports atomic commits of filesets and file moving/renaming. VC
+does not support all operations provided by GNU Arch, so you must
+sometimes invoke it from the command line.
+
+@cindex git
+@item
+Git is a distributed version control system invented by Linus Torvalds to support
+development of Linux (his kernel). It supports atomic commits of filesets and
+file moving/renaming. One significant feature of git is that it
+largely abolishes the notion of a single centralized repository;
+instead, each working copy of a git project is its own repository and
+coordination is done through repository-sync operations. VC supports
+most git operations, with the exception of news merges and repository
+syncing; these must be done from the command line.
+
+@cindex hg
+@cindex Mercurial
+@item
+Mercurial (hg) is a distributed version control system broadly
+resembling GNU Arch and git, with atomic fileset commits and file
+moving/renaming. Like git, it is fully decentralized. VC supports
+most Mercurial commands, with the exception of repository sync
+operations; this needs to be done from the command line.
+
+@cindex bzr
+@cindex Bazaar
+@item
+Bazaar (bzr) is a distributed version control system that supports both
+repository-based and distributed versioning, with atomic fileset
+commits and file moving/renaming. 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 has been dropped because of 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
+ A file @dfn{checked out} of a repository is called the @dfn{work
+file}. You edit the work file and make changes in it, as you would
+with an ordinary file. After you are done with a set of changes, you
+@dfn{check in} or @dfn{commit} the file; this records the changes in
+the repository, along with a log entry for those changes.
+
+@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 revisions 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.
+They can be locking-based or merging-based; they can be file-based or
+changeset-based; and they can be centralized or decentralized. VC
+handles all these modes of operation, but it cannot hide the differences.
+
+@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 checked in, with the latest changes that others have checked into
+the repository.
+
+ 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 check in 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 check in a change to a file that conflicts
+with a change checked in 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 ``checkin'' and ``checkout'' come from locking-based version
+control systems; newer version control systems have slightly different
+operations usually called ``commit'' and ``update'', but VC hides the
+differences between them as much as possible.
+
+@cindex files versus 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 in the
+system. Later systems, beginning with Subversion, are
+@dfn{changeset-based}: a checkin may include changes to several files,
+and the entire set of changes is treated as a unit by the system. 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.
+
+@cindex centralized vs. 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. At the limit, each developer has his/her own
+repository, and repository merges replace checkin/commit operations.
+
+ VC's job is to help you manage the traffic between your personal
+workfiles and a repository. Whether that repository is a single
+master or one of a network of peer repositories is not something VC
+has to care about. Thus, the difference between a centralized and a
+decentralized version control system is invisible to VC mode.
+
+@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 check in 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
+
+ When you visit a file that is under version control, Emacs indicates
+this on the mode line. For example, @samp{RCS-1.3} says that RCS is
+used for that file, and the current version is 1.3.
+
+ The character between the back-end name and the revision ID
+indicates the version control status of the file. @samp{-} means that
+the work file is not locked (if locking is in use), or not modified (if
+locking is not in use). @samp{:} indicates that the file is locked, or
+that it is modified. If the file is locked by some other user (for
+instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
+
+ 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. This menu is
+identical to the @samp{Tools / Version Control} menu item.
+
+@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 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.
+
+ Support for VC filesets and changeset-based version control systems
+is the main improvement to VC in Emacs 23. When you mark multi-file
+VC in a VC Directory buffer, VC operations treat them as a VC fileset,
+and operate on them all at once if the version control system is
+changeset-based. @xref{VC Directory Mode}.
+
+ 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.
+* Log Buffer:: Features available in log entry buffers.
+@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 the same as in the repository, it does nothing.
+
+@item
+If you have not changed the work file, but some other user has checked
+in changes to the repository, @kbd{C-x v v} merges those changes into
+the work file.
+
+@item
+If you have made modifications to the work file, @kbd{C-x v v}
+attempts to check in your changes. To do this, Emacs first reads the
+log entry for the new revision (@pxref{Log Buffer}). If some other
+user has checked in 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 will not be automatically merged from the
+repository. Nothing informs you if another user has checked in
+changes in the same file since you began editing it; when you check in
+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, @kbd{C-x v v} locks it, and makes it
+writable so that you can change it.
+
+@item
+If the file is locked by you, and contains changes, @kbd{C-x v v}
+checks in the changes. In order to do this, it 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, @kbd{C-x v v} releases the lock and makes the file
+read-only again.
+
+@item
+If the file is locked by some other user, @kbd{C-x v v} asks you 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 there is no such thing as stealing a lock.
+
+@node Advanced C-x v v
+@subsubsection Advanced Control in @kbd{C-x v v}
+
+@cindex revision ID to check in/out
+ 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 check in. 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
+@subsubsection Features of the Log Entry Buffer
+
+ When you check in changes, Emacs pops up a buffer called
+@samp{*VC-Log*} for you to enter a log entry.
+
+ After you have finished editing the log message, type @kbd{C-c C-c}
+to exit the buffer and commit the change.
+
+@findex log-edit-show-files
+@findex log-edit-show-diff
+ In the @samp{*VC-Log*} buffer, typing @kbd{C-c C-f}
+(@code{log-edit-show-files}) displays a list of files in the VC
+fileset you are committing. If you called @kbd{C-x v v} directly from
+a work file, the VC fileset consists of that single file, so this
+command is not very useful. If you called @kbd{C-x v v} from a VC
+directory buffer, the VC fileset may consist of multiple files
+(@pxref{VC Directory Mode}).
+
+@findex log-edit-insert-changelog
+ Type @kbd{C-c C-d} (@code{log-edit-show-diff}) to show a ``diff'' of
+the changes you have made (i.e., the differences between the work file
+and the repository revision from which you started editing the file).
+The diff is displayed in a special buffer in another window.
+@xref{Comparing Files}.
+
+ If you have written an entry in the @file{ChangeLog} (@pxref{Change
+Log}), type @kbd{C-c C-a} (@code{log-edit-insert-changelog}) to pull
+it into the @samp{*VC-Log*} buffer. If the topmost item in the
+@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 check in 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 check in 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 check in 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 ~ @var{revision} @key{RET}
+Examine revision @var{revision} of the visited file, in a buffer of its
+own.
+
+@item C-x v =
+Compare the buffer contents associated with the current
+fileset with the working revision(s) from which you started editing.
+
+@item C-u C-x v = @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET}
+Compare the specified two repository revisions of the current fileset.
+
+@item C-x v g
+Display an annotated version of the file: for each line, show the
+latest revision in which it was modified.
+@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 the current buffer contents
+of each file in the current VC fileset (saving them if necessary) with
+the repository revision 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 a special buffer in another window. @xref{Comparing
+Files}.
+
+@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.
+
+ 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.
+
+@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 Status:: Viewing the VC status of files.
+* 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 Status
+@subsubsection VC Status Commands
+
+@table @kbd
+@item C-x v l
+Display revision control state and change history.
+@end table
+
+@kindex C-x v l
+@findex vc-print-log
+ To view the detailed revision control status and history of a file,
+type @kbd{C-x v l} (@code{vc-print-log}). This pops up a special
+buffer named @samp{*vc-change-log*}, in a new window, that displays
+the history of changes to the current file, including the text of the
+log entries. The point is centered at the revision of the file that
+is currently being visited.
+
+ 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
+
+@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 checked in, 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 checked in to the repository---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} (@pxref{CVS Options}). 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 the @kbd{mouse-2} button.
+
+ 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 search on the marked files.
+
+ 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.
+
+ 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 check in 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 check in 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 check in 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 check in 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 check in 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
+
+@cindex 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
+check in the merged version afterwards.
+
+@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
@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
@node Tags
@section Tags Tables
-@cindex tags table
+@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
@noindent
The @code{etags} program reads the specified files, and writes a tags
-table named @file{TAGS} in the current working directory.
+table named @file{TAGS} in the current working directory. You can
+optionally specify a different file name for the tags table by using the
+@samp{--output=@var{file}} option; specifying @file{-} as a file name
+prints the tags table to standard output.
If the specified files don't exist, @code{etags} looks for
compressed versions of them and uncompresses them to read them. Under
directory where the tags file was initially written. This way, you can
move an entire directory tree containing both the tags file and the
source files, and the tags file will still refer correctly to the source
-files. If the tags file is in @file{/dev}, however, the file names are
+files. If the tags file is @file{-} or is in the @file{/dev} directory,
+however, the file names are
made relative to the current working directory. This is useful, for
example, when writing the tags to @file{/dev/stdout}.
It is possible to get through all the files in the tags table with a
single invocation of @kbd{M-x tags-query-replace}. But often it is
useful to exit temporarily, which you can do with any input event that
-has no special query replace meaning. You can resume the query replace
-subsequently by typing @kbd{M-,}; this command resumes the last tags
-search or replace command that you did.
+has no special query replace meaning. You can resume the query
+replace subsequently by typing @kbd{M-,}; this command resumes the
+last tags search or replace command that you did. For instance, to
+skip the rest of the current file, you can type @kbd{M-> M-,}.
The commands in this section carry out much broader searches than the
@code{find-tag} family. The @code{find-tag} commands search only for