-@node Version Control
-@section Version Control
-@cindex version control
-
- @dfn{Version control systems} are packages that can record multiple
-versions of a source file, usually storing the unchanged parts of the
-file just once. Version control systems also record history 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 different version control systems---currently, it supports CVS,
-GNU Arch, RCS, Subversion, and SCCS. Of these, the GNU
-project distributes CVS, GNU Arch, and RCS. We also have free
-software to replace SCCS, known as CSSC; if you are using SCCS and
-don't want to make the incompatible change to RCS or CVS, you can
-switch to CSSC.
-
- VC is enabled by default in Emacs. To disable it, 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.
-* 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:
-@dfn{reversibility}, @dfn{concurrency}, and @dfn{history}.
-
- The most basic capability you get from a version-control system is
-reversibility, the ability to back up to a saved, known-good state when
-you discover that some modification you did was a mistake or a bad idea.
-
- Version-control systems also support concurrency, the ability to
-have many people modifying the same collection of code or documents
-knowing that conflicting modifications can be detected and resolved.
-
- Version-control systems give you the capability to attach a history
-to your data, 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
-become a vitally important form of communication among developers.
-
-@node Version Control Systems
-@subsubsection Supported Version Control Systems
-
-@cindex back end (version control)
- VC currently works with many different version control systems or
-``back ends'': SCCS, RCS, CVS, Subversion, GNU Arch,
-git, and Mercurial.
-@comment Omitting bzr because support is very scratchy and incomplete.
-
-@cindex SCCS
- SCCS was the first version-control system ever built, and was long ago
-superseded by later and more advanced ones; Emacs supports it only for
-backward compatibility and historical reasons. VC compensates for
-certain features missing in SCCS (tag names for releases, for example) by
-implementing them itself. Some other VC features, such as multiple
-branches, are not available with SCCS. Since SCCS is non-free you
-should not use it; use its free replacement CSSC instead. But you
-should use CSSC only if for some reason you cannot use a more
-recent and better-designed version-control system.
-
-@cindex RCS
- 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. You
-cannot use RCS over the network, though, and it only works at the level
-of individual files, rather than projects. You should use it if you
-want a simple, yet reliable tool for handling individual files.
-
-@cindex CVS
- CVS is the free version control system that was until recently (as of
-2007) used for the majority of free software projects, though it is now
-being superseded by other systems. It allows concurrent
-multi-user development either locally or over the network. Some of its
-shortcomings, corrected by newer systems such as Subversion or GNU Arch,
-are that it lacks atomic commits or support for renaming files. VC
-supports all basic editing operations under CVS, but 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
- Subversion is a free version control system designed to be similar
-to CVS but without CVS's problems, and is now (2007) rapidly
-superseding CVS. Subversion supports atomic commits of filesets, and
-versions directories, symbolic links, meta-data, renames, copies, and
-deletes. It can be used via http or via its own protocol.
-
-@cindex GNU Arch
-@cindex Arch
- GNU Arch is a new version control system that is designed for
-distributed work. It differs in many ways from old well-known
-systems, such as CVS and RCS. It supports different transports for
-interoperating between users, offline operations, and it has good
-branching and merging features. It also supports atomic commits of
-filesets, and keeps a history of file renaming and moving. VC
-does not support all operations provided by GNU Arch, so you must
-sometimes invoke it from the command line, or use a specialized
-module.
-
-@cindex git
- git is a version-control system invented by Linus Torvalds to
-support Linux kernel development. Like GNU Arch, it supports atomic
-commits of filesets, and keeps a history of file renaming and
-moving. 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 fully supports git, except
-that it doesn't do news merges and repository sync operations must
-be done from the command line.
-
-@cindex hg
-@cindex Mercurial
- Mercurial is a distributed version-control systems broadly
-resembling GNU Arch and git, with atomic fileset commits and
-rename/move histories. Like git it is fully decentralized.
-VC fully supports Mercurial, except for repository sync operations
-which still need to be done from the command line.
-
-@node VCS Concepts
-@subsubsection Concepts of Version Control
-
-@cindex repository
-@cindex registered file
- When a file is under version control, we also 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 plus its
-change history---enough to reconstruct the current version or any
-earlier version. The repository will also contain a @dfn{log entry} for
-each change to the file, describing in words what was modified in that
-revision.
-
-@cindex work file
-@cindex checking out files
- A file checked out of a version-control repository is sometimes
-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, which
-records the changes in the repository, along with a log entry for
-them.
-
-@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}. In older VCSes (such as SCCS and RCS),
-the simplest kind of revision ID consisted of a @dfn{dot-pair};
-integers (the @dfn{major} and @dfn{minor} revisions) separated by a
-dot. Newer VCSes tend to use @dfn{monotonic} revision IDs that are
-simple integers counting from 1.
-
- To go beyond these basic concepts, you will need to understand three
-ways in which version-control systems can differ from each other. They
-can be locking or merging; they can be file-based or changeset-based;
-and they can be centralized or decentralized. VC handles all these
-choices, but they lead to differing behaviors which you will need
-to understand as you use it.
-
-@cindex locking versus merging
- A version control system typically has some mechanism to coordinate
-between users who want to change the same file. One method is
-@dfn{locking} (analogous to the locking that Emacs uses to detect
-simultaneous editing of a file, but distinct from it). In a locking
-system, such as SCCS, you must @dfn{lock} a file before you start to
-edit it. The other method is @dfn{merging}; the system tries to
-merge your changes with other people's changes when you check them in.
-
- With version control locking, work files are normally read-only so
-that you cannot change them. You ask the version control system to make
-a work file writable for you by locking it; only one user can do
-this at any given time. When you check in your changes, that unlocks
-the file, making the work file read-only again. This allows other users
-to lock the file to make further changes.
-
- By contrast, a merging system lets each user check out and modify a
-work file at any time. When you check in a file, the system will
-attempt to merge your changes with any others checked into the
-repository since you checked out the file.
-
- 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.
-
- 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.
-Most later version-control systems, such as GNU Arch, git, and
-Mercurial, have been based exclusively on merging rather than locking.
-This is because experience has shown that the merging-based approach
-is generally superior to the locking one, both in convenience to
-developers and in minimizing the number and severity of conflicts that
-actually occur.
-
- While it is rather unlikely that anyone will ever again build a
-fundamentally locking-based rather than merging-based version-control
-system in the future, merging-based version-systems sometimes have locks
-retrofitted onto them for reasons having nothing to do with technology.
-@footnote{Usually the control-freak instincts of managers.} For this
-reason, and to support older systems still in use, VC mode supports
-both locking and merging version control and tries to hide the differences
-between them as much as possible.
-
-@cindex files versus changesets.
- On SCCS, RCS, CVS, and other early version-control systems, checkins
-and other operations are @dfn{file-based}; each file has its own
-@dfn{master file} with 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 under these
-may include changes to several files and that change set is treated as
-a unit by the system. Any comment associated with the change belongs
-to no single file, but is attached to the changeset itself.
-
- Changeset-based version control is in general both more flexible and
-more powerful than file-based version control; usually, when a change to
-multiple files has to be backed out, it's good to be able to easily
-identify and remove all of it. But it took some years for designers to
-figure that out, and while file-based systems are passing out of use
-there are lots of legacy repositories still to be dealt with at time of
-writing in 2007.
-
- In fact, older versions of VC mode supported only file-based systems,
-leading to some unhappy results when it was used to drive
-changeset-based ones---the Subversion support, for example, used to break
-up changesets into multiple per-file commits. This has been fixed, but
-it has left a legacy in VC-mode's terminology. The terms ``checkin''
-and ``checkout'' are associated with file-based and locking-based
-systems and a bit archaic; nowadays those operations are usually called
-``commit'' and ``update''.
-
-@cindex centralized vs. decentralized
- 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.
-It has two important problems. One is that a single repository is a
-single point of failure---if the repository server is down all work
-stops. The other is that you need to be connected live to the server to
-do checkins and checkouts; if you're offline, you can't work.
-
- Newer version-control systems like GNU Arch, git, Mercurial, and Bzr
-are @dfn{decentralized}. 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.
-
-@iftex
-(@pxref{CVS Options,,,emacs-xtra, Specialized Emacs Features}).
-@end iftex
-@ifnottex
-(@pxref{CVS Options}).
-@end ifnottex
-
-
-@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 revision control system can have @emph{two}
-types of log for changes. One is the log maintained by the
-revision control system: each time you check in a change, you must
-fill out a @dfn{log entry} for the change (@pxref{Log Buffer}). This
-kind of log is called the @dfn{version control log}, also the
-@dfn{revision control log}, @dfn{RCS log}, or @dfn{CVS 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 well merit a @file{ChangeLog} file in each major directory.
-@xref{Change Log}.
-
- Actually, the fact that both kinds of log exist is partly a legacy from
-file-based version control. Changelogs are a GNU convention, later
-more widely adopted, that help developers to get a changeset-based
-view of a project even when its version-control system has that
-information split up in multiple file-based logs.
-
- Changeset-based version systems, on the other hand, often maintain
-a changeset-based modification log for the entire system that makes
-ChangeLogs mostly redundant. The only advantage ChangeLogs retain is that
-it may be 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 when you
-check in the change. 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}.
-
-@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
-
-@menu
-* Selecting A Fileset:: Choosing a set of files to operate on
-* Doing The Right Thing:: Stepping forward in the development cycle
-* VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS.
-* VC With A Merging VCS:: Without locking: default mode for CVS.
-* Advanced C-x v v:: Advanced features available with a prefix argument.
-* Log Buffer:: Features available in log entry buffers.
-@end menu
-
-@node Selecting A Fileset
-@subsubsection Choosing the scope of your command
-
-@cindex filesets
- Most VC commands operate on @dfn{filesets}. A fileset is a
-group of files that you have chosen to treat as a unit at the
-time you perform the command. Filesets are the way that VC
-mode bridges the gap between file-based and changeset-based
-version-control systems.
-
- If you are visiting a version-controlled file in the current buffer,
-the default fileset for any command is simply that one file. If you
-are visiting a VC directory buffer, and some files in it are marked,
-your fileset is the marked files only.
-
- All files in a fileset must be under the same version-control system.
-If they are not, VC mode will fail when you attempt to execute
-a command on the fileset.
-
- VC filesets are, essentially, a way to pass multiple file
-arguments as a group to underlying version-control commands. For
-example, on Subversion a checkin with more than one file in its
-fileset will become a joint commit, as though you had typed
-@command{svn commit} with those file arguments at the shell command
-line in the directory of the selected buffer.
-
- If you are accustomed to earlier versions of VC, the change in behavior
-you will notice is in the directory mode. Other than @kbd{C-x v v}, most
-VC-mode commands once operated on only one file selected by the line
-the cursor is on. The change in the behavior of @kbd{C-x v v} outside
-VC Directory Mode is more subtle. Formerly it operated in parallel on all
-marked files, but did not pass them to the version-control backends as
-a group. Now it does, which enables VC to drive changeset-based
-version-control systems.
-
- Emacs uses the concept of named filesets elsewhere
-(@pxref{Filesets}) to allow you to view and visit files in functional
-groups. Unlike those, VC filesets are not named and don't persist
-across sessions.
-
-@node Doing The Right Thing
-@subsubsection Performing the next operation in the development cycle
-
- The principal VC command is an all-purpose command that performs
-either locking or check-in on your current fileset, depending on
-the situation.
-
-@table @kbd
-@itemx C-x v v
-Perform the next logical version control operation on this file.
-@end table
-
-@findex vc-next-action
-@kindex C-x v v
- The precise action of this command depends on the state of the file,
-and whether the version control system uses locking or merging. SCCS and
-RCS normally use locking; CVS and Subversion normally use
-merging but can be configured to do locking. Later systems such as
-GNU Arch and Mercurial always use merging.
-
-@node VC With A Locking VCS
-@subsubsection Basic Version Control with Locking
-
- If locking is used for the file (as with SCCS, and RCS in its default
-mode), @kbd{C-x v v} can either lock a file or check it in:
-
-@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 VC With A Merging VCS
-@subsubsection Basic Version Control with Merging
-
- When your version-control system is merging-based rather than
-locking-based---the default for CVS and Subversion, and the way GNU
-Arch and more modern systems always work---work files are always
-writable; you do not need to do anything before you begin to edit 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 in
-the work file.
-
- Here is what @kbd{C-x v v} does when using a merging-based system
-(such as CVS or Subversion in their default merging mode):
-
-@itemize @bullet
-@item
-If some other user has checked in changes into the repository, Emacs
-asks you whether you want to merge those changes into your own work
-file. You must do this before you can check in your own changes. (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}.
-
-@item
-If there are no new changes in the repository, but you have made
-modifications in your work file, @kbd{C-x v v} checks in your changes.
-In order to do this, it first reads the log entry for the new revision.
-@xref{Log Buffer}.
-
-@item
-If the file is not modified, the @kbd{C-x v v} does nothing.
-@end itemize
-
- These rules also apply when you use RCS in the mode that does not
-require locking, except that automatic merging of changes from the
-repository is not implemented. Unfortunately, this means that nothing
-informs you if another user has checked in changes in the same file
-since you began editing it, and when this happens, his changes will be
-effectively removed when you check in your revision (though they will
-remain in the repository, so they will not be entirely lost). You must
-therefore verify that the current revision is unchanged, before you
-check in your changes.
-
- In addition, locking is possible with RCS even in this mode, although
-it is not required; @kbd{C-x v v} with an unmodified file locks the
-file, just as it does with RCS in its normal (locking) mode.
-
- Later systems like CVS, Subversion and Arch will notice conflicting
-changes in the repository automatically and notify you when they occur.
-
-@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, @kbd{C-x v v} first reads a log entry. It
-pops up a buffer called @samp{*VC-Log*} for you to enter the log entry.
-
- Sometimes the @samp{*VC-Log*} buffer contains default text when you enter it,
-typically the last log message entered. If it does, mark and point
-are set around the entire contents of the buffer so that it is easy to
-kill the contents of the buffer with @kbd{C-w}.
-
-@findex log-edit-insert-changelog
- If you work by first writing entries in the @file{ChangeLog}
-(@pxref{Change Log}) and afterwards committing the change under revision
-control, you can generate the Log Edit text from the ChangeLog using
-@kbd{C-c C-a} (@kbd{log-edit-insert-changelog}). This looks for
-entries for the file(s) concerned in the top entry in the ChangeLog
-and uses those paragraphs as the log text. This text is only inserted
-if the top entry was made under your user name on the current date.
-@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.
-
- In the @samp{*VC-Log*} buffer, @kbd{C-c C-f} (@kbd{M-x
-log-edit-show-files}) shows the list of files to be committed in case
-you need to check that. (This can be a list of more than one file if
-you use VC Directory Mode or PCL-CVS.)
-@iftex
-@xref{VC Directory Mode,,,emacs-xtra, Specialized Emacs Features},
-@end iftex
-@ifnottex
-@xref{VC Directory Mode},
-@end ifnottex
-and @ref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs
-Front-End to CVS}.)
-
- When you have finished editing the log message, type @kbd{C-c C-c} to
-exit the buffer and commit the change.
-
- To abort 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
-confirm it with @kbd{C-c C-c}.
-
- However, 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
-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 the file with per-line revision information and using colors.
-@end table
-
-@findex vc-revision-other-window
-@kindex C-x v ~
- To examine an old revision in its entirety, visit the file and then type
-@kbd{C-x v ~ @var{revision} @key{RET}} (@code{vc-revision-other-window}).
-This puts the text of revision @var{revision} in a file named
-@file{@var{filename}.~@var{revision}~}, and visits it in its own buffer
-in a separate window. (In RCS, you can also select an old revision
-and create a branch from it. @xref{Branches}.)
-
-@findex vc-diff
-@kindex C-x v =
-@kbd{C-x v =} compares the current buffer contents of each file in the
-current fileset (saving them in the file if necessary) with the
-repository revision from which you started editing each file (this is not
-necessarily the latest revision of the file). The diff will be displayed
-in a special buffer in another window.
-
-@findex vc-diff
-@kindex C-u C-x v =
- You can compare two repository revisions of the current fileset with
-the command @kbd{C-u C-x v =} (@code{vc-diff}). @kbd{C-u C-x v =} reads
-two revision ID or tags. The diff will be displayed in a special
-buffer in another window.
-
- You can specify a checked-in revision by its ID; an empty input
-specifies the current contents of the work file (which may be different
-from all the checked-in revisions). You can also specify a tag or branch name
-@iftex
-(@pxref{Tags,,,emacs-xtra, Specialized Emacs Features})
-@end iftex
-@ifnottex
-(@pxref{Tags})
-@end ifnottex
-instead of one or both revision ID.
-
- Note that if your version-control system is file-oriented (SCCS,
-RCS, CVS) rather than fileset-oriented (Subversion, GNU Arch, git,
-Mercurial) specifying a revision of a multiple-file fileset by
-revision ID (as opposed to a symbolic tag name) is
-unlikely to return diffs that are connected in any meaningful way.
-
- If you invoke @kbd{C-u 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 will 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. When you
-invoke @code{diff} this way, in addition to the options specified by
-@code{diff-switches} (@pxref{Comparing Files}), it receives those
-specified by @code{vc-diff-switches}, plus those specified for the
-specific back end by @code{vc-@var{backend}-diff-switches}. For
-instance, when the version control back end is RCS, @code{diff} uses
-the options in @code{vc-rcs-diff-switches}. The
-@samp{vc@dots{}diff-switches} variables are @code{nil} by default.
-
- 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 and using colors to enhance the visual
-appearance, with the command @kbd{M-x 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 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 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.
-@end table
-
-@node Secondary VC Commands
-@subsection The Secondary Commands of VC
-
- This section explains the secondary commands of VC, those that you might
-use once a day.
-
-@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.
-@ifnottex
-* VC Directory Mode:: Listing files managed by version control.
-* VC Directory Commands:: Commands to use in a VC directory buffer.
-@end ifnottex
-@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}). It displays the history of
-changes to the current file, including the text of the log entries. The
-output appears in a separate window. The point is centered at the
-revision of the file that is currently being visited.
-
- In the change log buffer, you can use the following keys to move
-between the logs of revisions and of files, to view past revisions, 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
-@iftex
-(@pxref{VC Directory Mode,,,emacs-xtra, Specialized Emacs Features}).
-@end iftex
-@ifnottex
-(@pxref{VC Directory Mode}).
-@end ifnottex
-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
-@iftex
-(@pxref{VC Directory Mode,,,emacs-xtra, Specialized Emacs Features}).
-@end iftex
-@ifnottex
-(@pxref{VC Directory Mode}).
-@end ifnottex
-It also takes a numeric prefix argument as a repeat count.
-
-@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 when the revision indicated on the
-current line 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}). This leaves the file unlocked; if locking
-is in use, you must first lock the file again before you change it
-again. @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.
-
-@ifnottex
-@c vc1-xtra.texi needs extra level of lowering.
-@lowersections
-@include vc1-xtra.texi
-@raisesections
-@end ifnottex
-
-@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 vc2-xtra.texi
-@end ifnottex
-