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}
@node Basic VC Editing
@subsection Basic Editing under Version Control
+@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 Dired 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 wil throw an error when you attempt to execute
+a command on the fileset.
+
+ 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 used to earlier versions of VC, the change in behavior you
+will notice is in VC-Dired mode. Other than @kbd{C-x v v}, most VC-mode
+commands used to operate on only one file selected by the line the
+cursor is on. The change in the behavior of @kbd{C-x v v} 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.
+
+@node Doing the next logical 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, depending on the situation.
+either locking or check-in on your current fileset, depending on
+the situation.
@table @kbd
@itemx C-x v v
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. To do
-this, use the history of previous log entries. 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).
+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-Dired 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
own.
@item C-x v =
-Compare the current buffer contents with the focus version from which
-you started editing.
+Compare the buffer contents of the current
+fileset with the focus version from which you started editing.
-@item C-u C-x v = @var{file} @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET}
-Compare the specified two versions of @var{file}.
+@item C-u C-x v = @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET}
+Compare the specified two repository versions of the current fileset.
@item C-x v g
Display the file with per-line version information and using colors.
@findex vc-diff
@kindex C-x v =
- It is usually more convenient to compare two versions of the file,
-with the command @kbd{C-x v =} (@code{vc-diff}). Plain @kbd{C-x v =}
-compares the current buffer contents (saving them in the file if
-necessary) with the master version from which you started editing the
-file (this is not necessarily the latest version of the file).
-@kbd{C-u C-x v =}, with a numeric argument, reads a file name and two
-version numbers, then compares those versions of the specified file.
-Both forms display the output in a special buffer in another window.
+@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 version from which you started editing each file (this is not
+necessarily the latest version 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 versions of the current fileset with
+the command @kbd{C-u C-x v =} (@code{vc-diff}). @kbd{C-u C-x v =} reads
+two version numbers or tags. The diff will be displayed in a special
+buffer in another window.
You can specify a checked-in version by its number; an empty input
specifies the current contents of the work file (which may be different
@end ifnottex
instead of one or both version numbers.
- If you supply a directory name instead of the name of a registered
-file, this command compares the two specified versions of all registered
-files in that directory and its subdirectories.
+ Note that if your version-control system is file-oriented (SCCS, RCS,
+CVS) rather than fileset-oriented (CVS, Subversion, GNU Arch) specifying
+a version of a multiple-file fileset by number (as opposed to a snapshot
+name or RSCCS/RCS tag) 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 Dired
+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
then decide not to change it.
@kindex C-x v c
-@findex vc-cancel-version
+@findex vc-rollback
To cancel a change that you already checked in, use @kbd{C-x v c}
-(@code{vc-cancel-version}). This command discards all record of the
-most recent checked-in version, but only if your work file corresponds
-to that version---you cannot use @kbd{C-x v c} to cancel a version
-that is not the latest on its branch. @kbd{C-x v c} also offers to
-revert your work file and buffer to the previous version (the one that
-precedes the version that is deleted).
-
- If you answer @kbd{no}, VC keeps your changes in the buffer, and locks
-the file. The no-revert option is useful when you have checked in a
-change and then discover a trivial error in it; you can cancel the
-erroneous check-in, fix the error, and check the file in again.
-
- When @kbd{C-x v c} does not revert the buffer, it unexpands all
-version control headers in the buffer instead
-@iftex
-(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}).
-@end iftex
-@ifnottex
-(@pxref{Version Headers}).
-@end ifnottex
-This is because the buffer no longer corresponds to any existing
-version. If you check it in again, the check-in process will expand
-the headers properly for the new version number.
-
- However, it is impossible to unexpand the RCS @samp{@w{$}Log$} header
-automatically. If you use that header feature, you have to unexpand it
-by hand---by deleting the entry for the version that you just canceled.
-
- Be careful when invoking @kbd{C-x v c}, as it is easy to lose a lot of
-work with it. To help you be careful, this command always requires
-confirmation with @kbd{yes}. Note also that this command is disabled
-under CVS, because canceling versions is very dangerous and discouraged
-with CVS.
+(@code{vc-rollback}). This command discards all record of the most
+recent checked-in version, but only if your work file corresponds to
+that version---you cannot use @kbd{C-x v c} to cancel a version 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.
projects / emacs.git / commitdiff