[Emacs-diffs] Changes to emacs/doc/emacs/files.texi,v

[Chong Yidong]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Chong Yidong <cyd>      08/10/31 22:00:49

Index: files.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/emacs/files.texi,v
retrieving revision 1.43
retrieving revision 1.44
diff -u -b -r1.43 -r1.44
--- files.texi  31 Oct 2008 09:31:43 -0000      1.43
+++ files.texi  31 Oct 2008 22:00:48 -0000      1.44
@@ -30,14 +30,12 @@
 @end ifnottex
 * Auto Save::           Auto Save periodically protects against loss of data.
 * File Aliases::        Handling multiple names for one file.
-* Version Control::     Version control systems (RCS, CVS and SCCS).
 * Directories::         Creating, deleting, and listing file directories.
 * Comparing Files::     Finding where two files differ.
 * Diff Mode::           Mode for editing file differences.
 * Misc File Ops::       Other things you can do on files.
 * Compressed Files::    Accessing compressed files.
 * File Archives::       Operating on tar, zip, jar etc. archive files.
-* Document Files::      Viewing PDF, PS and DVI files.
 * Remote Files::        Accessing files on other sites.
 * Quoted File Names::   Quoting special characters in file names.
 * File Name Cache::     Completion against a list of files you often use.
@@ -1164,1351 +1162,6 @@
 than the name you specify.  Setting @code{find-file-visit-truename} also
 implies the effect of @code{find-file-existing-other-name}.
 
address@hidden Version Control
address@hidden Version Control
address@hidden 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}
address@hidden
-(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
address@hidden iftex
address@hidden
-(@pxref{Customizing VC}).
address@hidden ifnottex
-
-
address@hidden
-* 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.
address@hidden
-* 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.
address@hidden ifnottex
address@hidden menu
-
address@hidden Introduction to VC
address@hidden 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.
-
address@hidden
-* 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.
address@hidden menu
-
address@hidden Why Version Control?
address@hidden Understanding the problems it addresses
-
-  Version control systems provide you with three important
-capabilities:
-
address@hidden @bullet
address@hidden
address@hidden: the ability to back up to a previous state if you
-discover that some modification you did was a mistake or a bad idea.
-
address@hidden
address@hidden: the ability to have many people modifying the same
-collection of files knowing that conflicting modifications can be
-detected and resolved.
-
address@hidden
address@hidden: 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.
address@hidden itemize
-
address@hidden Version Control Systems
address@hidden Supported Version Control Systems
-
address@hidden back end (version control)
-  VC currently works with many different version control systems or
address@hidden ends}:
-
address@hidden @bullet
-
address@hidden SCCS
address@hidden
-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.
-
address@hidden CSSC
address@hidden
-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.
-
address@hidden RCS
address@hidden
-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.
-
address@hidden CVS
address@hidden
-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.
-
address@hidden SVN
address@hidden Subversion
address@hidden
-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.
-
address@hidden GNU Arch
address@hidden Arch
address@hidden
-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.
-
address@hidden git
address@hidden
-Git is a distributed version control system invented by Linus Torvalds to 
support
-Linux kernel development.  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.
-
address@hidden hg
address@hidden Mercurial
address@hidden
-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.
-
address@hidden bzr
address@hidden Bazaar
address@hidden
-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.
address@hidden 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.
-
address@hidden VCS Concepts
address@hidden Concepts of Version Control
-
address@hidden repository
address@hidden registered file
-   When a file is under version control, we say that it is
address@hidden in the version control system.  The system has a
address@hidden 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.
-
address@hidden work file
address@hidden 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
address@hidden in} or @dfn{commit} the file; this records the changes in
-the repository, along with a log entry for those changes.
-
address@hidden revision
address@hidden 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
-ways in which version control systems can differ from each other.
-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 choices, but they lead to differing behaviors which
-you will need to understand as you use it.
-
address@hidden 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
address@hidden 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.
-
-  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.  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.  Sometimes, however, newer version control systems may have
-locks retrofitted onto them for reasons having nothing to do with
address@hidden the control-freak instincts of managers.}.
-
-  VC mode supports both locking and merging version control and tries
-to hide the differences between them as much as possible.
-
address@hidden 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
address@hidden: 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.  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 as of this writing (2008).
-
-  Prior to Emacs 23, VC supported only file-based systems, leading to
-unhappy results when it was used to drive changeset-based
-systems---the Subversion support, for example, used to break up
-changesets into multiple per-file commits.  This has been fixed, but
-it has left a mark in VC'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''.
-
address@hidden centralized vs. decentralized version control
-  Early version control systems were designed around a
address@hidden model in which each project has only one repository
-used by all developers.  SCCS, RCS, CVS, and Subversion share this
-kind of model.  One problem with this approach is that a single
-repository is a single point of failure---if the repository server is
-down, all work stops.
-
-  Newer version control systems like GNU Arch, git, Mercurial, and
-Bazaar 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.
-
address@hidden Types of Log File
address@hidden Types of Log File
address@hidden types of log file
address@hidden log File, types of
address@hidden 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.
address@hidden 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 somewhat redundant.  One advantage that ChangeLogs 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
address@hidden 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
address@hidden
address@hidden
-(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
address@hidden iftex
address@hidden
-(@pxref{Change Logs and VC}).
address@hidden ifnottex
-
address@hidden VC Mode Line
address@hidden 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{Version Control} menu item, which can be found
-in the @samp{Tools} menu on the menu bar.
-
address@hidden 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
address@hidden to @code{t}, Auto Revert mode updates
-the version control status information every
address@hidden seconds, even if the work file itself is
-unchanged.  The resulting CPU usage depends on the version control
-system, but is usually not excessive.
-
address@hidden Basic VC Editing
address@hidden Basic Editing under Version Control
-
address@hidden filesets
-   Most VC commands operate on @dfn{VC filesets}.  A VC fileset is a
-group of one or more files that are treated as a unit, for the
-purposes of version control.
-
-   If you are visiting a version-controlled file in the current
-buffer, the VC fileset is simply that one file.  If you are visiting 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 on the current VC fileset, depending on the situation.  You
-can call @kbd{C-x v v} from a version-controlled file, or from the VC
-Directory buffer.
-
address@hidden @kbd
address@hidden C-x v v
-Perform the next logical version control operation on the VC fileset.
address@hidden table
-
address@hidden vc-next-action
address@hidden 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.
-
-  If you are accustomed to previous versions of VC, most of the
-changes to VC in Emacs 23 are found in VC directory mode (@pxref{VC
-Directory Mode}).  When multiple files are marked in the VC directory
-buffer, they are treated as a VC fileset; typing @kbd{C-x v v} in the
-VC directory buffer passes them to the version control backends as a
-single unit.  Other commands in VC directory mode now act on the VC
-fileset, rather than the file on the current line.  These changes
-allow VC to interoperate correctly with changeset-based version
-control systems.
-
-  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.
-
address@hidden
-* 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.
address@hidden menu
-
address@hidden VC With A Merging VCS
address@hidden 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:
-
address@hidden @bullet
address@hidden
-If the work file is the same as in the repository, it does nothing.
-
address@hidden
-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.
-
address@hidden
-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}}.
address@hidden
address@hidden 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:
address@hidden 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}).
-
address@hidden VC With A Locking VCS
address@hidden 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
address@hidden
-If the file is not locked, @kbd{C-x v v} locks it, and makes it
-writable so that you can change it.
-
address@hidden
-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}.
-
address@hidden
-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.
-
address@hidden
-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.
address@hidden itemize
-
-  These rules also apply when you use CVS in locking mode, except
-that there is no such thing as stealing a lock.
-
address@hidden Advanced C-x v v
address@hidden Advanced Control in @kbd{C-x v v}
-
address@hidden 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.
-
address@hidden @bullet
address@hidden
-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}).
-
address@hidden
-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.
-
address@hidden
address@hidden 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
address@hidden
-(@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs
-Features}).
address@hidden iftex
address@hidden
-(@pxref{Local Version Control}).
address@hidden ifnottex
-
address@hidden itemize
-
address@hidden Log Buffer
address@hidden Features of the Log Entry Buffer
-
-  When you check in changes, Emacs pops up a buffer called
address@hidden 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.
-
address@hidden log-edit-show-files
address@hidden 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}).
-
address@hidden 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.
address@hidden 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
address@hidden 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.
address@hidden
address@hidden Logs and VC,,,emacs-xtra, Specialized Emacs Features},
address@hidden iftex
address@hidden
address@hidden Logs and VC},
address@hidden 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).
-
address@hidden 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}.
-
address@hidden Old Revisions
address@hidden 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.
-
address@hidden @kbd
address@hidden C-x v ~ @var{revision} @key{RET}
-Examine revision @var{revision} of the visited file, in a buffer of its
-own.
-
address@hidden C-x v =
-Compare the buffer contents associated with the current
-fileset with the working revision(s) from which you started editing.
-
address@hidden 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.
-
address@hidden C-x v g
-Display an annotated version of the file: for each line, show the
-latest revision in which it was modified.
address@hidden table
-
address@hidden vc-revision-other-window
address@hidden 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,
address@hidden is either the desired revision ID (@pxref{VCS
-Concepts}), or the name of a tag or branch
address@hidden
-(@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}).
address@hidden iftex
address@hidden
-(@pxref{Tags}).
address@hidden ifnottex
-This command puts the text of the old revision in a file named
address@hidden@address@hidden, and visits it in its own
-buffer in a separate window.
-
address@hidden vc-diff
address@hidden 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}.
-
address@hidden vc-diff
address@hidden C-u C-x v =
-  To compare two arbitrary revisions of the current VC fileset, call
address@hidden 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
address@hidden
-(@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}).
address@hidden iftex
address@hidden
-(@pxref{Tags}).
address@hidden 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.
-
address@hidden vc-diff-switches
address@hidden 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
address@hidden (@pxref{Comparing Files}), it receives those
-specified by @code{vc-diff-switches}, plus those specified for the
-specific back end by @address@hidden  For
-instance, when the version control back end is CVS, @code{diff} uses
-the options in @code{vc-cvs-diff-switches}.  The
address@hidden@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
address@hidden 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.)
-
address@hidden vc-annotate
address@hidden 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:
-
address@hidden @kbd
address@hidden 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.
-
address@hidden n
-Annotate the next revision---the one after the revision currently
-annotated.  A numeric prefix argument is a repeat count.
-
address@hidden j
-Annotate the revision indicated by the current line.
-
address@hidden 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.
-
address@hidden f
-Show in a buffer the file revision indicated by the current line.
-
address@hidden 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.
-
address@hidden 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.
-
address@hidden 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.
-
address@hidden w
-Annotate the working revision--the one you are editing.  If you used
address@hidden and @kbd{n} to browse to other revisions, use this key to
-return to your working revision.
-
address@hidden v
-Toggle the annotation visibility.  This is useful for looking just at
-the file contents without distraction from the annotations.
address@hidden table
-
address@hidden Secondary VC Commands
address@hidden The Secondary Commands of VC
-
-  This section explains the secondary commands of VC.
-
address@hidden
-* Registering::         Putting a file under version control.
-* VC Status::           Viewing the VC status of files.
-* VC Undo::             Canceling changes before or after check-in.
address@hidden menu
-
address@hidden Registering
address@hidden Registering a File for Version Control
-
address@hidden C-x v i
address@hidden vc-register
-  You can put any file under version control by simply visiting it, and
-then typing @address@hidden v i}} (@code{vc-register}).
-
address@hidden @kbd
address@hidden C-x v i
-Register the visited file for version control.
address@hidden 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}
address@hidden
-(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
address@hidden iftex
address@hidden
-(@pxref{Customizing VC}).
address@hidden 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.
-
address@hidden vc-default-init-revision
address@hidden 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
address@hidden, 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.
-
address@hidden vc-initial-comment
-  If @code{vc-initial-comment} is address@hidden, @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}).
-
address@hidden VC Status
address@hidden VC Status Commands
-
address@hidden @kbd
address@hidden C-x v l
-Display revision control state and change history.
address@hidden table
-
address@hidden C-x v l
address@hidden 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:
-
address@hidden @kbd
address@hidden 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.
-
address@hidden 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.
-
address@hidden 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.
-
address@hidden 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.
-
address@hidden a
-Annotate the revision indicated by the current line.
-
address@hidden e
-Modify the change comment displayed at point.  Note that not all VC
-systems support modifying change comments.
-
address@hidden f
-Visit the revision indicated at the current line, like typing @kbd{C-x
-v ~} and specifying this revision's ID (@pxref{Old Revisions}).
-
address@hidden 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.
-
address@hidden 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.
address@hidden table
-
address@hidden VC Undo
address@hidden Undoing Version Control Actions
-
address@hidden @kbd
address@hidden C-x v u
-Revert the buffer and the file to the working revision from which you started
-editing the file.
-
address@hidden C-x v c
-Remove the last-entered change from the master for the visited file.
-This undoes your last check-in.
address@hidden table
-
address@hidden C-x v u
address@hidden 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.
-
address@hidden C-x v c
address@hidden 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.
-
address@hidden VC Directory Mode
address@hidden VC Directory Mode
-
address@hidden C-x v d
address@hidden 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.
-
address@hidden PCL-CVS
address@hidden cvs
address@hidden CVS directory mode
-  The VC Directory buffer described here works with all the version
-control systems that VC supports.  Another more powerful facility,
-designed specifically for CVS, is called PCL-CVS.  @xref{Top, , About
-PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}.
-
-  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
-omitted; if all files in a directory are up-to-date, the directory is
-omitted as well.  (However, the directory in which @code{vc-dir} was
-run will always be shown as @file{./}.)  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
address@hidden 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:
-
address@hidden
address@hidden
-                       ./
-    modified           file1.c
-    needs-update       file2.c
-    needs-merge        file3.c
address@hidden group
address@hidden smallexample
-
address@hidden
-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.
-
address@hidden vc-stay-local
address@hidden 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
address@hidden) is 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
address@hidden 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.
-
address@hidden 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
address@hidden; you can customize this by setting the variable
address@hidden
-
address@hidden
-* VC Directory Commands:: Commands to use in a VC directory buffer.
address@hidden menu
-
address@hidden VC Directory Commands
address@hidden 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
address@hidden 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} toggles hiding of 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{=},
address@hidden, @kbd{l}, @kbd{i}, and @kbd{v} behave as through prefixed with
address@hidden 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 a set of files,
-it requires that all of those files must be either in the same state or
-in compatible states; otherwise it will throw an error (added,
-modified and removed states are considered compatible).  Note that 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.
-
address@hidden Branches
address@hidden Multiple Branches of a File
address@hidden branch (version control)
address@hidden 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
address@hidden  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.
-
address@hidden head revision
-  If you omit the final component of a dot-pair revision ID, that is called a
address@hidden 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.
-
address@hidden
-* 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.
address@hidden menu
-
address@hidden Switching Branches
address@hidden 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.
-
address@hidden Creating Branches
address@hidden 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
address@hidden 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.
-
address@hidden Merging
address@hidden Merging Branches
-
address@hidden 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.
-
address@hidden @kbd
address@hidden C-x v m (vc-merge)
-Merge changes into the work file.
address@hidden table
-
address@hidden C-x v m
address@hidden 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
address@hidden, 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
address@hidden  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.
-
address@hidden conflicts
address@hidden 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.
-
address@hidden @w here is so CVS won't think this is a conflict.
address@hidden
address@hidden
address@hidden<}<<<<<< name
-  @var{User A's version}
-=======
-  @var{User B's version}
address@hidden>}>>>>>> 1.11
address@hidden group
address@hidden smallexample
-
address@hidden 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.
-
address@hidden Multi-User Branching
address@hidden 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
address@hidden 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
address@hidden
-(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}).
address@hidden iftex
address@hidden
-(@pxref{Version Headers}).
address@hidden 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.
-
address@hidden
address@hidden vc1-xtra.texi
address@hidden ifnottex
-
 @node Directories
 @section File Directories
 
@@ -2989,160 +1642,6 @@
 need these programs to look at the archive table of contents, only to
 extract or manipulate the subfiles in the archive.
 
-
address@hidden Document Files
address@hidden Document Files
address@hidden mode, pdf, ps, dvi
address@hidden DocView mode
address@hidden mode, DocView
address@hidden document files
address@hidden doc-view-mode
-
-DocView mode is a document viewer for Emacs (@code{doc-view-mode}).
-It's capable of displaying PDF, PS and DVI files inside an Emacs buffer
-and provides some convenience features like slicing, zooming and
-searching inside the document.
-
address@hidden doc-view-cache-directory
-This is done by using @command{gs} (GhostScript) to convert the document
-to a set of PNG images which are then displayed.  In order to omit
-double conversions of documents those images are cached in
address@hidden
-
address@hidden doc-view-minor-mode
address@hidden doc-view-toggle-display
-By default Emacs opens all pdf and dvi files using DocView mode.  You'll
-be greeted with a welcome screen and as soon as the first page's
-conversion finished, it'll be displayed.  PostScript files are opened
-with @code{ps-mode} by default, but additionally
address@hidden is enabled, which adds the binding @kbd{C-c
-C-c} (@code{doc-view-toggle-display}) and toggles between the editing
-mode (@code{ps-mode} in case of PS files, @code{fundamental-mode} in
-case of PDF or DVI files) and DocView mode.
-
address@hidden doc-view-enlarge
address@hidden doc-view-shrink
-You can enlarge or shrink the document with @kbd{+}
-(@code{doc-view-enlarge}) and @kbd{-} (@code{doc-view-shrink}).
-
-The DocView buffer can be buried with @kbd{q} and killed with @kbd{k}.
-
address@hidden
-* Navigation:: Navigation inside DocView buffers.
-* Searching::  Searching inside documents.
-* Slicing::    Specifing which part of pages should be displayed.
-* Conversion:: Influencing and triggering converison.
address@hidden menu
-
address@hidden Navigation
address@hidden Navigation
-
-Inside DocView mode you can scroll the current page using the usual
-Emacs movement keys, that is the arrow keys or @kbd{C-p}, @kbd{C-n},
address@hidden and @kbd{C-f}.
-
address@hidden doc-view-next-page
address@hidden doc-view-previous-page
-To go to the next page use @kbd{n}, @address@hidden or @kbd{C-x ]}
-(@code{doc-view-next-page}), to go to the previous page use @kbd{p},
address@hidden@key{prior}} or @kbd{C-x [} (@code{doc-view-previous-page}).
-
address@hidden doc-view-scroll-up-or-next-page
address@hidden doc-view-scroll-down-or-previous-page
-While reading a document it's convenient to scroll the current page and
-switch to the next one if it's already scrolled to the bottom.  This
-functionality is bound to @address@hidden
-(@code{doc-view-scroll-up-or-next-page}).  @address@hidden will do the
-same in the other direction
-(@code{doc-view-scroll-down-or-previous-page}).
-
address@hidden doc-view-first-page
address@hidden doc-view-last-page
-To go to the first page use @kbd{M-<} (@code{doc-view-first-page}), to
-go to the last one use @kbd{M->} (@code{doc-view-last-page}).
-
address@hidden doc-view-goto-page
-To jump to a page by its number use @kbd{M-g M-g} or @kbd{M-g g}
-(@code{doc-view-goto-page}).
-
address@hidden Searching
address@hidden Searching
-
-It's possible to search for a regular expression (@pxref{Regexps})
-inside documents.  In order to do that, the document file will be
-converted to text and the search will be performed in the text file.
-The interface to searching is inspired by @code{isearch}
-(@pxref{Incremental Search}).
-
address@hidden doc-view-search
address@hidden doc-view-search-backward
-To initiate a search use @kbd{C-s} (@code{doc-view-search}) or @kbd{C-r}
-(@code{doc-view-search-backward}).  You'll be queried for a regular
-expression and after hitting @address@hidden the number of matches will
-be echoed.  Navigation between the matches is done by pressing @kbd{C-s}
-and @kbd{C-r} again.
-
address@hidden doc-view-show-tooltip
-Since there's no possibility to show the match inside the image itself,
-a tooltip will be shown at the mouse position which lists all matching
-lines of the current page.  You can force the tooltip to be shown with
address@hidden (@code{doc-view-show-tooltip}).
-
-To initiate a new search call @code{doc-view-search} with a prefix
-argument, i.e. @kbd{C-u C-s} or @kbd{C-u C-r} for a backward search.
-
address@hidden Slicing
address@hidden Slicing
-
-Quite often documents have huge margins for printing.  These are
-annoying when reading the document on a computer, because they use up
-screen space and thus can force inconvenient scrolling.
-
address@hidden doc-view-set-slice
address@hidden doc-view-set-slice-using-mouse
-To prevent you from that DocView lets you select the slice of the pages
-you're interested in.  To do that hit @kbd{s s}
-(@code{doc-view-set-slice}) to enter the top left pixel position and the
-slice's width and height.  A more convenient method is provided by
address@hidden m} (@code{doc-view-set-slice-using-mouse}), where you use the
-mouse to select the slice.
-
address@hidden doc-view-reset-slice
-To reset the selected slice use @kbd{s r} (@code{doc-view-reset-slice}).
-
address@hidden Conversion
address@hidden Conversion
-
-As said before DocView mode will automatically convert the document
-files when visiting them unless @code{doc-view-cache-directory} already
-contains the converted PNG images.  In that case it'll use the cached
-files.
-
address@hidden doc-view-clear-cache
-You can clean up the cache directory with @code{M-x
-doc-view-clear-cache}.
-
-If a document has changed, it'll be converted anew when visiting it.
-DocView recognizes documents by the md5 sum of their contents.
-
address@hidden doc-view-kill-proc
address@hidden doc-view-kill-proc-and-buffer
-To force a reconversion of the currently viewed document hit @kbd{r} or
address@hidden (@code{revert-buffer}).  Killing the converter process
-associated with the current buffer can be done with @kbd{K}
-(@code{doc-view-kill-proc}).  The key @kbd{k} will do the same and
-additionally kill the DocView buffer
-(@code{doc-view-kill-proc-and-buffer}).
-
-The zoom commands @kbd{+} (@code{doc-view-enlarge}) and @kbd{-}
-(@code{doc-view-shrink}) will also reconvert the current document using
-another resolution.  The current page will be converted first.
-
address@hidden doc-view-resolution
-The default resolution for conversion can be customized via the variable
address@hidden
-
-
 @node Remote Files
 @section Remote Files