changeset 107676:e0b20352344e

Document VC changes: vc-log-show-limit and vc-print-root-log. * maintaining.texi (VC With A Merging VCS): C-x v v now creates a repository if there is none. (VC Change Log): Rename from VC Status. Document vc-log-show-limit and vc-print-root-log. (Old Revisions): Copyedits. * emacs.texi: Update.
author Chong Yidong <cyd@stupidchicken.com>
date Thu, 25 Mar 2010 18:57:13 -0400
parents 429ef7abe3df
children 6dc6d78ccf45
files doc/emacs/ChangeLog doc/emacs/emacs.texi doc/emacs/maintaining.texi etc/NEWS
diffstat 4 files changed, 108 insertions(+), 69 deletions(-) [+]
line wrap: on
line diff
--- a/doc/emacs/ChangeLog	Thu Mar 25 17:14:17 2010 -0400
+++ b/doc/emacs/ChangeLog	Thu Mar 25 18:57:13 2010 -0400
@@ -1,5 +1,11 @@
 2010-03-25  Chong Yidong  <cyd@stupidchicken.com>
 
+	* maintaining.texi (VC With A Merging VCS): C-x v v now creates a
+	repository if there is none.
+	(VC Change Log): Rename from VC Status.  Document vc-log-show-limit and
+	vc-print-root-log.
+	(Old Revisions): Copyedits.
+
 	* programs.texi (Program Modes): Mention Javascript mode.
 
 	* text.texi (HTML Mode): Note that nXML is now the default XML mode.
--- a/doc/emacs/emacs.texi	Thu Mar 25 17:14:17 2010 -0400
+++ b/doc/emacs/emacs.texi	Thu Mar 25 18:57:13 2010 -0400
@@ -794,7 +794,7 @@
 The Secondary Commands of VC
 
 * Registering::         Putting a file under version control.
-* VC Status::           Viewing the VC status of files.
+* VC Change Log::       Viewing the VC Change Log.
 * VC Undo::             Canceling changes before or after check-in.
 
 VC Directory Mode
--- a/doc/emacs/maintaining.texi	Thu Mar 25 17:14:17 2010 -0400
+++ b/doc/emacs/maintaining.texi	Thu Mar 25 18:57:13 2010 -0400
@@ -403,10 +403,10 @@
 consists of the marked files (@pxref{VC Directory Mode}).
 
   The principal VC command is an all-purpose command, @kbd{C-x v v}
-(@code{vc-next-action}), that performs either locking, merging or a
-check-in (depending on the situation) on the current VC fileset.  You
-can use @kbd{C-x v v} in a file-visiting buffer or in a VC Directory
-buffer.
+(@code{vc-next-action}), that performs either registration, locking,
+merging or a check-in (depending on the situation) on the current VC
+fileset.  You can use @kbd{C-x v v} in a file-visiting buffer or in a
+VC Directory buffer.
 
 @table @kbd
 @itemx C-x v v
@@ -461,23 +461,31 @@
 
 @itemize @bullet
 @item
-If the work file is the same as in the repository, it does nothing.
+If the work file is in a directory that is not controlled by any
+version control system, prompt for a repository type.  Then, create a
+version control repository of that type and register the file with it.
+
+@item
+If the work file is in a directory that is controlled by a version
+control system but not registered with it, register the file.
+
+@item
+If the work file is the same as in the repository, do nothing.
 
 @item
 If you have not changed the work file, but some other user has checked
-in changes to the repository, @kbd{C-x v v} merges those changes into
-the work file.
+in changes to the repository, merge those changes into the work file.
 
 @item
-If you have made modifications to the work file, @kbd{C-x v v}
-attempts to check in your changes.  To do this, Emacs first reads the
-log entry for the new revision (@pxref{Log Buffer}).  If some other
-user has checked in changes to the repository since you last checked
-it out, the checkin fails.  In that case, type @kbd{C-x v v} again to
-merge those changes into your own work file; this puts the work file
-into a ``conflicted'' state.  Type @kbd{C-x v v} to clear the
-``conflicted'' state; VC then regards the file as up-to-date and
-modified, and you can try to check it in again.
+If you have made modifications to the work file, 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}}.
@@ -485,15 +493,15 @@
 @end itemize
 
   These rules also apply when you use RCS in its ``non-locking'' mode,
-except that changes will not be automatically merged from the
-repository.  Nothing informs you if another user has checked in
-changes in the same file since you began editing it; when you check in
-your revision, his changes are removed (however, they remain in the
-repository and are thus not irrevocably lost).  Therefore, you must
-verify that the current revision is unchanged before checking in your
-changes.  In addition, locking is possible with RCS even in this mode:
-@kbd{C-x v v} with an unmodified file locks the file, just as it does
-with RCS in its normal locking mode (@pxref{VC With A Locking VCS}).
+except that changes are not automatically merged from the repository.
+Nothing informs you if another user has checked in changes in the same
+file since you began editing it; when you check in your revision, his
+changes are removed (however, they remain in the repository and are
+thus not irrevocably lost).  Therefore, you must verify that the
+current revision is unchanged before checking in your changes.  In
+addition, locking is possible with RCS even in this mode: @kbd{C-x v
+v} with an unmodified file locks the file, just as it does with RCS in
+its normal locking mode (@pxref{VC With A Locking VCS}).
 
 @node VC With A Locking VCS
 @subsubsection Basic Version Control with Locking
@@ -501,26 +509,25 @@
   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
+@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.
+If the file is not locked, lock it and make it writable, so that you
+can change it.
 
 @item
-If the file is locked by you, and contains changes, @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}.
+If the file is locked by you, and contains changes, check in the
+changes.  In order to do this, Emacs first reads the log entry for the
+new revision.  @xref{Log Buffer}.
 
 @item
 If the file is locked by you, but you have not changed it since you
-locked it, @kbd{C-x v v} releases the lock and makes the file
-read-only again.
+locked it, release 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.
+If the file is locked by some other user, ask whether you want to
+``steal the lock'' from that user.  If you say yes, the file becomes
+locked by you, but a message is sent to the person who had formerly
+locked the file, to inform him of what has happened.
 @end itemize
 
   These rules also apply when you use CVS in locking mode, except
@@ -639,20 +646,19 @@
 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 ~
+Prompt for a revision of the visited file, and visit it in a buffer of
+its own (@code{vc-revision-other-window}).
 
 @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.
+Compare the buffer associated with the current fileset with the
+working revision(s) from which you started editing (@code{vc-diff}).
+With a prefix argument, prompt for two revisions of the current
+fileset and compare them.
 
 @item C-x v g
 Display an annotated version of the file: for each line, show the
-latest revision in which it was modified.
+latest revision in which it was modified (@code{vc-annotate}).
 @end table
 
 @findex vc-revision-other-window
@@ -801,7 +807,7 @@
 
 @menu
 * Registering::         Putting a file under version control.
-* VC Status::           Viewing the VC status of files.
+* VC Change Log::       Viewing the VC Change Log.
 * VC Undo::             Canceling changes before or after check-in.
 @end menu
 
@@ -857,22 +863,36 @@
 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
+@node VC Change Log
+@subsubsection VC Change Log
 
 @table @kbd
 @item C-x v l
-Display revision control state and change history.
+Display revision control state and change history
+(@code{vc-print-log}).
+
+@item C-x v L
+Display the change history for the current repository
+(@code{vc-print-root-log}).
 @end table
 
 @kindex C-x v l
 @findex vc-print-log
-  To view the detailed revision control status and history of a file,
-type @kbd{C-x v l} (@code{vc-print-log}).  This pops up a special
-buffer named @samp{*vc-change-log*}, in a new window, that displays
-the history of changes to the current file, including the text of the
-log entries.  The point is centered at the revision of the file that
-is currently being visited.
+  The command @kbd{C-x v l} (@code{vc-print-log}) displays a buffer
+named @samp{*vc-change-log*} in a new window.  This buffer lists the
+changes to the current file, including the associated log entries.
+(These are the log entries associated with the version control system,
+i.e. the ones you enter via the @samp{*VC-Log*} buffer.  @xref{Log
+Buffer}.)  Point is centered at the revision of the file currently
+being visited.  With a prefix argument, the command prompts for the
+revision to center on, and the maximum number of revisions to display.
+
+@findex vc-print-root-log
+  Type @kbd{C-x v L} (@code{vc-print-root-log}) to display a
+@samp{*vc-change-log*} buffer showing the history of the
+version-controlled directory tree as a whole.  With a prefix argument,
+the command prompts for the maximum number of revisions to display.
+RCS, SCCS, and CVS do not support this feature.
 
   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
@@ -926,6 +946,16 @@
 indicated on the current line did when it was committed.
 @end table
 
+@vindex vc-log-show-limit
+Because fetching many log entries can be slow, the
+@samp{*vc-change-log*} buffer displays no more than 2000 revisions by
+default.  The variable @code{vc-log-show-limit} specifies this limit;
+if you set the value to zero, that removes the limit.  You can also
+increase the number of revisions shown in an existing
+@samp{*vc-change-log*} buffer by clicking on the @samp{Show 2X
+entries} or @samp{Show unlimited entries} buttons at the end of the
+buffer.  However, RCS, SCCS, and CVS do not support this feature.
+
 @node VC Undo
 @subsubsection Undoing Version Control Actions
 
--- a/etc/NEWS	Thu Mar 25 17:14:17 2010 -0400
+++ b/etc/NEWS	Thu Mar 25 18:57:13 2010 -0400
@@ -292,21 +292,24 @@
 connection methods "dav", "davs", "obex" and "synce".
 
 ** VC and related modes
-
++++
 *** When using C-x v v or C-x v i on a unregistered file that is in a
 directory not controlled by any VCS, ask the user what VC backend to
 use to create a repository, create a new repository and register the
 file.
-
-*** FIXME: add info about the new VC functions: vc-root-diff and
-vc-root-print-log once they stabilize.
-
-*** The log functions (C-x v l and C-x v L) do not show the full log
-by default anymore.  The number of entries shown can be chosen
-interactively with a prefix argument, by customizing
-vc-log-show-limit.  The log buffer display buttons that can be used
-to change the number of entries shown.
-RCS, SCCS, CVS do not support this feature.
++++
+*** New command `vc-root-print-log', bound to `C-x v L'.
+This displays a `*vc-change-log*' buffer showing the history of the
+version-controlled directory tree as a whole.
+
+*** FIXME: vc-root-diff.
++++
+*** `C-x v l' and `C-x v L' do not show the full log by default.
+The number of entries shown can be chosen interactively with a prefix
+argument, or by customizing vc-log-show-limit.  The `*vc-change-log*'
+buffer now contains buttons at the end of the buffer, which can be
+used to increase the number of entries shown.  RCS, SCCS, and CVS do
+not support this feature.
 
 *** vc-annotate supports annotations through file copies and renames,
 it displays the old names for the files and it can show logs/diffs for
@@ -319,7 +322,7 @@
 
 *** When a file is not found, VC will not try to check it out of RCS anymore.
 
-*** Diff and log operations can be used from dired buffers.
+*** Diff and log operations can be used from Dired buffers.
 
 *** vc-git changes