Latest version from Cyclic

1 files changed, 150 insertions, 19 deletions

diff --git a/gnu/usr.bin/cvs/doc/cvsclient.texi b/gnu/usr.bin/cvs/doc/cvsclient.texi
index 6f0139976b7..c9224e3d720 100644
--- a/gnu/usr.bin/cvs/doc/cvsclient.texi
+++ b/gnu/usr.bin/cvs/doc/cvsclient.texi
@@ -479,7 +479,7 @@ For the @samp{-D} option to the @code{annotate}, @code{co}, @code{diff},
 and @code{update} requests, the server should support two formats:
 
 @example
-26 May 1997 13:01:40 GMT  ; @r{RFC 822 as modified by RFC 1123}
+26 May 1997 13:01:40 -0000  ; @r{RFC 822 as modified by RFC 1123}
 5/26/1997 13:01:40 GMT    ; @r{traditional}
 @end example
 
@@ -491,7 +491,9 @@ least support RFC 822/1123 format.  Clients are encouraged to use this
 format too (traditionally the command line CVS client has just passed
 along the date format specified by the user, however).
 
-For @code{Mod-time}, see the description of that response.
+The @code{Mod-time} response and @code{Checkin-time} request use RFC
+822/1123 format (see the descriptions of that response and request for
+details).
 
 For @code{Notify}, see the description of that request.
 
@@ -521,7 +523,7 @@ in use, connection, authentication, etc., are already taken care of.
 
 The @code{Root} request must be sent only once, and it must be sent
 before any requests other than @code{Valid-responses},
-@code{valid-requests}, @code{UseUnchanged}, or @code{init}.
+@code{valid-requests}, @code{UseUnchanged}, @code{Set} or @code{init}.
 
 @item Valid-responses @var{request-list} \n
 Response expected: no.
@@ -606,6 +608,99 @@ Each @code{Directory} request specifies a brand-new
 @var{local-directory} and @var{repository} are never relative to paths
 specified in any previous @code{Directory} request.
 
+Here's a more complex example, in which we request an update of a
+working directory which has been checked out from multiple places in the
+repository.
+
+@example
+C: Argument dir1
+C: Directory dir1
+C: /home/foo/repos/mod1
+. . .
+C: Argument dir2
+C: Directory dir2
+C: /home/foo/repos/mod2
+. . .
+C: Argument dir3
+C: Directory dir3/subdir3
+C: /home/foo/repos/mod3
+. . .
+C: update
+@end example
+
+While directories @code{dir1} and @code{dir2} will be handled in similar
+fashion to the other examples given above, @code{dir3} is slightly
+different from the server's standpoint.  Notice that module @code{mod3}
+is actually checked out into @code{dir3/subdir3}, meaning that directory
+@code{dir3} is either empty or does not contain data checked out from
+this repository.  
+
+The above example will work correctly in @sc{cvs} 1.10.1 and later.  The
+server will descend the tree starting from all directories mentioned in
+@code{Argument} requests and update those directories specifically
+mentioned in @code{Directory} requests.
+
+Previous versions of @sc{cvs} (1.10 and earlier) do not behave the same
+way.  While the descent of the tree begins at all directories mentioned
+in @code{Argument} requests, descent into subdirectories only occurs if
+a directory has been mentioned in a @code{Directory} request.
+Therefore, the above example would succeed in updating @code{dir1} and
+@code{dir2}, but would skip @code{dir3} because that directory was not
+specifically mentioned in a @code{Directory} request.  A functional
+version of the above that would run on a 1.10 or earlier server is as
+follows:
+
+@example
+C: Argument dir1
+C: Directory dir1
+C: /home/foo/repos/mod1
+. . .
+C: Argument dir2
+C: Directory dir2
+C: /home/foo/repos/mod2
+. . .
+C: Argument dir3
+C: Directory dir3
+C: /home/foo/repos/.
+. . .
+C: Directory dir3/subdir3
+C: /home/foo/repos/mod3
+. . .
+C: update
+@end example
+
+Note the extra @code{Directory dir3} request.  It might be better to use
+@code{Emptydir} as the repository for the @code{dir3} directory, but the
+above will certainly work.
+
+One more peculiarity of the 1.10 and earlier protocol is the ordering of
+@code{Directory} arguments.  In order for a subdirectory to be
+registered correctly for descent by the recursion processor, its parent
+must be sent first.  For example, the following would not work to update
+@code{dir3/subdir3}:
+
+@example
+. . .
+C: Argument dir3
+C: Directory dir3/subdir3
+C: /home/foo/repos/mod3
+. . .
+C: Directory dir3
+C: /home/foo/repos/.
+. . .
+C: update
+@end example
+
+The implementation of the server in 1.10 and earlier writes the
+administration files for a given directory at the time of the
+@code{Directory} request.  It also tries to register the directory with
+its parent to mark it for recursion.  In the above example, at the time
+@code{dir3/subdir3} is created, the physical directory for @code{dir3}
+will be created on disk, but the administration files will not have been
+created.  Therefore, when the server tries to register
+@code{dir3/subdir3} for recursion, the operation will silently fail
+because the administration files do not yet exist for @code{dir3}.
+
 @item Max-dotdot @var{level} \n
 Response expected: no.
 Tell the server that @var{level} levels of directories above the
@@ -627,9 +722,10 @@ responses.
 @item Sticky @var{tagspec} \n
 Response expected: no.  Tell the server that the directory most recently
 specified with @code{Directory} has a sticky tag or date @var{tagspec}.
-The first character of @var{tagspec} is @samp{T} for a tag, or @samp{D}
-for a date.  The remainder of @var{tagspec} contains the actual tag or
-date.
+The first character of @var{tagspec} is @samp{T} for a tag, @samp{D}
+for a date, or some other character supplied by a Set-sticky response
+from a previous request to the server.  The remainder of @var{tagspec}
+contains the actual tag or date, again as supplied by Set-sticky.
 
 The server should remember @code{Static-directory} and @code{Sticky}
 requests for a particular directory; the client need not resend them
@@ -672,6 +768,29 @@ Typically this will be a file being added via an @code{add} or
 @code{import} request.  The client may not send both @code{Kopt} and
 @code{Entry} for the same file.
 
+@item Checkin-time @var{time} \n
+For the file specified by the next @code{Modified} request, use
+@var{time} as the time of the checkin.  The @var{time} is in the format
+specified by RFC822 as modified by RFC1123.  The client may specify any
+timezone it chooses; servers will want to convert that to their own
+timezone as appropriate.  An example of this format is:
+
+@example
+26 May 1997 13:01:40 -0400
+@end example
+
+There is no requirement that the client and server clocks be
+synchronized.  The client just sends its recommendation for a timestamp
+(based on file timestamps or whatever), and the server should just believe
+it (this means that the time might be in the future, for example).
+
+Note that this is not a general-purpose way to tell the server about the
+timestamp of a file; that would be a separate request (if there are
+servers which can maintain timestamp and time of checkin separately).
+
+This request should affect the @code{import} request, and may optionally
+affect the @code{ci} request or other relevant requests if any.
+
 @item Modified @var{filename} \n
 Response expected: no.  Additional data: mode, \n, file transmission.
 Send the server a copy of one locally modified file.  @var{filename} is
@@ -1134,7 +1253,7 @@ Response expected: yes.
 Any unrecognized request expects a response, and does not
 contain any additional data.  The response will normally be something like
 @samp{error  unrecognized request}, but it could be a different error if
-a previous command which doesn't expect a response produced an error.
+a previous request which doesn't expect a response produced an error.
 @end table
 
 When the client is done, it drops the connection.
@@ -1330,6 +1449,11 @@ synchronized.  The server just sends its recommendation for a timestamp
 (based on its own clock, presumably), and the client should just believe
 it (this means that the time might be in the future, for example).
 
+If the server does not send @code{Mod-time} for a given file, the client
+should pick a modification time in the usual way (usually, just let the
+operating system set the modification time to the time that the CVS
+command is running).
+
 @item Checksum @var{checksum}\n
 The @var{checksum} applies to the next file sent (that is,
 @code{Checksum} is a file update modifying response
@@ -1564,6 +1688,23 @@ MT fname @var{name}
 MT -updated
 @end example
 
+The @code{importmergecmd} tag is used when doing an import which has
+conflicts.  The client can use it to report how to merge in the newly
+imported changes.  The @var{count} is the number of conflicts.  The
+newly imported changes can be merged by running the following command:
+@smallexample
+cvs checkout -j @var{tag1} -j @var{tag2} @var{repository}
+@end smallexample
+
+@example
+MT +importmergecmd
+MT conflicts @var{count}
+MT mergetag1 @var{tag1}
+MT mergetag2 @var{tag2}
+MT repository @var{repository}
+MT -importmergecmd
+@end example
+
 @node Example
 @section Example
 
@@ -1751,6 +1892,8 @@ working directory, and the meaning of sending @code{Entries} without
 A number of enhancements are possible.  Also see the file @sc{todo} in
 the @sc{cvs} source distribution, which has further ideas concerning
 various aspects of @sc{cvs}, some of which impact the protocol.
+Similarly, the @code{http://www.cyclic.com} site, in particular the
+@cite{Development of CVS} page.
 
 @itemize @bullet
 @item
@@ -1762,18 +1905,6 @@ could be handled by a package like VC for emacs).  This would also allow
 local operation of @code{cvs diff} without arguments.
 
 @item
-The current procedure for @code{cvs update} is highly sub-optimal if
-there are many modified files.  One possible alternative would be to
-have the client send a first request without the contents of every
-modified file, then have the server tell it what files it needs.  Note
-the server needs to do the what-needs-to-be-updated check twice (or
-more, if changes in the repository mean it has to ask the client for
-more files), because it can't keep locks open while waiting for the
-network.  Perhaps this whole thing is irrelevant if there is a multisite
-capability (as noted in @sc{todo}), and therefore the rcsmerge can be
-done with a repository which is connected via a fast connection.
-
-@item
 The fact that @code{pserver} requires an extra network turnaround in
 order to perform authentication would be nice to avoid.  This relates to
 the issue of reporting errors; probably the clean solution is to defer