sync from MirBSD
[alioth/cvs.git] / doc / cvsclient.texi
1 \input texinfo @c -*- texinfo -*-
2
3 @setfilename cvsclient.info
4 @set MBSDPATCHLEVEL -MirOS-0AB8.4
5 @tex
6  % set PA4 paper size (can print on both DIN ISO A4 and US Letter)
7  \globaldefs = 1%
8  \afourpaper%
9  \internalpagesizes{46\baselineskip}{160mm}%
10   {\voffset}{\hoffset}%
11   {\bindingoffset}{36pt}%
12   {28truecm}{21truecm}%
13  \globaldefs = 0%
14 @end tex
15 @comment $MirOS: src/gnu/usr.bin/cvs/doc/cvsclient.texi,v 1.11 2017/11/18 22:37:52 tg Exp $
16 @include version-client.texi
17
18 @dircategory Programming
19 @direntry
20 * cvsclient: (cvsclient).      The CVS client/server protocol.
21 @end direntry
22
23 @node Top
24 @top CVS Client/Server
25
26 This document describes the client/server protocol used by CVS.  It does
27 not describe how to use or administer client/server CVS; for that,
28 @pxref{Top, the regular CVS manual,, cvs, the regular CVS manual}.
29 This specification applies to
30 @sc{cvs} version @value{VERSION}@value{MBSDPATCHLEVEL} and up.
31
32 @menu
33 * Introduction::      What is CVS and what is the client/server protocol for?
34 * Goals::             Basic design decisions, requirements, scope, etc.
35 * Connection and Authentication::  Various ways to connect to the server
36 * Password scrambling::  Scrambling used by pserver
37 * Protocol::          Complete description of the protocol
38 * Protocol Notes::    Possible enhancements, limitations, etc. of the protocol
39 @end menu
40
41 @node Introduction
42 @chapter Introduction
43
44 CVS is a version control system (with some additional configuration
45 management functionality).  It maintains a central @dfn{repository}
46 which stores files (often source code), including past versions,
47 information about who modified them and when, and so on.  People who
48 wish to look at or modify those files, known as @dfn{developers}, use
49 CVS to @dfn{check out} a @dfn{working directory} from the repository, to
50 @dfn{check in} new versions of files to the repository, and other
51 operations such as viewing the modification history of a file.  If
52 developers are connected to the repository by a network, particularly a
53 slow or flaky one, the most efficient way to use the network is with the
54 CVS-specific protocol described in this document.
55
56 Developers, using the machine on which they store their working
57 directory, run the CVS @dfn{client} program.  To perform operations
58 which cannot be done locally, it connects to the CVS @dfn{server}
59 program, which maintains the repository.  For more information on how
60 to connect see @ref{Connection and Authentication}.
61
62 This document describes the CVS protocol.  Unfortunately, it does not
63 yet completely document one aspect of the protocol---the detailed
64 operation of each CVS command and option---and one must look at the CVS
65 user documentation, @file{cvs.texinfo}, for that information.  The
66 protocol is non-proprietary (anyone who wants to is encouraged to
67 implement it) and an implementation, known as CVS, is available under
68 the GNU General Public License.  The CVS distribution, containing this
69 implementation, @file{cvs.texinfo}, and a copy (possibly more or less up
70 to date than what you are reading now) of this document,
71 @file{cvsclient.texi}, can be found at the usual GNU FTP sites, with a
72 filename such as @file{cvs-@var{version}.tar.gz}.
73
74 This is version @value{VERSION} of the protocol specification.  This
75 version number is intended only to aid in distinguishing different
76 versions of this specification.  Although the specification is currently
77 maintained in conjunction with the CVS implementation, and carries the
78 same version number, it also intends to document what is involved with
79 interoperating with other implementations (such as other versions of
80 CVS); see @ref{Requirements}.  This version number should not be used
81 by clients or servers to determine what variant of the protocol to
82 speak; they should instead use the @code{valid-requests} and
83 @code{Valid-responses} mechanism (@pxref{Protocol}), which is more
84 flexible.
85
86 @node Goals
87 @chapter Goals
88
89 @itemize @bullet
90 @item
91 Do not assume any access to the repository other than via this protocol.
92 It does not depend on NFS, rdist, etc.
93
94 @item
95 Providing a reliable transport is outside this protocol.  The protocol
96 expects a reliable transport that is transparent (that is, there is no
97 translation of characters, including characters such as
98 linefeeds or carriage returns), and can transmit all 256 octets (for
99 example for proper handling of binary files, compression, and
100 encryption).  The encoding of characters specified by the protocol (the
101 names of requests and so on) is the invariant ISO 646 character set (a
102 subset of most popular character sets including ASCII and others).  For
103 more details on running the protocol over the TCP reliable transport,
104 see @ref{Connection and Authentication}.
105
106 @item
107 Security and authentication are handled outside this protocol (but see
108 below about @samp{cvs kserver} and @samp{cvs pserver}).
109
110 @item
111 The protocol makes it possible for updates to be atomic with respect to
112 checkins; that is if someone commits changes to several files in one cvs
113 command, then an update by someone else would either get all the
114 changes, or none of them.  The current @sc{cvs} server can't do this,
115 but that isn't the protocol's fault.
116
117 @item
118 The protocol is, with a few exceptions, transaction-based.  That is, the
119 client sends all its requests (without waiting for server responses),
120 and then waits for the server to send back all responses (without
121 waiting for further client requests).  This has the advantage of
122 minimizing network turnarounds and the disadvantage of sometimes
123 transferring more data than would be necessary if there were a richer
124 interaction.  Another, more subtle, advantage is that there is no need
125 for the protocol to provide locking for features such as making checkins
126 atomic with respect to updates.  Any such locking can be handled
127 entirely by the server.  A good server implementation (such as the
128 current @sc{cvs} server) will make sure that it does not have any such
129 locks in place whenever it is waiting for communication with the client;
130 this prevents one client on a slow or flaky network from interfering
131 with the work of others.
132
133 @item
134 It is a general design goal to provide only one way to do a given
135 operation (where possible).  For example, implementations have no choice
136 about whether to terminate lines with linefeeds or some other
137 character(s), and request and response names are case-sensitive.  This
138 is to enhance interoperability.  If a protocol allows more than one way
139 to do something, it is all too easy for some implementations to support
140 only some of them (perhaps accidentally).
141 @c I vaguely remember reading, probably in an RFC, about the problems
142 @c that were caused when some people decided that SMTP should accept
143 @c other line termination (in the message ("DATA")?) than CRLF.  However, I
144 @c can't seem to track down the reference.
145 @end itemize
146
147 @node Connection and Authentication
148 @chapter How to Connect to and Authenticate Oneself to the CVS server
149
150 Connection and authentication occurs before the CVS protocol itself is
151 started.  There are several ways to connect.
152
153 @table @asis
154 @item server
155 If the client has a way to execute commands on the server, and provide
156 input to the commands and output from them, then it can connect that
157 way.  This could be the usual rsh (port 514) protocol, Kerberos rsh,
158 SSH, or any similar mechanism.  The client may allow the user to specify
159 the name of the server program; the default is @code{cvs}.  It is
160 invoked with one argument, @code{server}.  Once it invokes the server,
161 the client proceeds to start the cvs protocol.
162
163 @item kserver
164 The kerberised server listens on a port (in the current implementation,
165 by having inetd call "cvs kserver") which defaults to 1999.  The client
166 connects, sends the usual kerberos authentication information, and then
167 starts the cvs protocol.  Note: port 1999 is officially registered for
168 another use, and in any event one cannot register more than one port for
169 CVS, so GSS-API (see below) is recommended instead of kserver as a way
170 to support kerberos.
171
172 @item pserver
173 The name @dfn{pserver} is somewhat confusing.  It refers to both a
174 generic framework which allows the CVS protocol to support several
175 authentication mechanisms, and a name for a specific mechanism which
176 transfers a username and a cleartext password.  Servers need not support
177 all mechanisms, and in fact servers will typically want to support only
178 those mechanisms which meet the relevant security needs.
179
180 The pserver server listens on a port (in the current
181 implementation, by having inetd call "cvs pserver") which defaults to
182 2401 (this port is officially registered).  The client
183 connects, and sends the following:
184
185 @itemize @bullet
186 @item
187 the string @samp{BEGIN AUTH REQUEST}, a linefeed, 
188 @item
189 the cvs root, a linefeed,
190 @item
191 the username, a linefeed,
192 @item
193 the password trivially encoded (see @ref{Password scrambling}), a
194 linefeed,
195 @item
196 the string @samp{END AUTH REQUEST}, and a linefeed.
197 @end itemize
198
199 The client must send the
200 identical string for cvs root both here and later in the
201 @code{Root} request of the cvs
202 protocol itself.  Servers are encouraged to enforce this restriction.
203 The possible server responses (each of which is followed by a linefeed)
204 are the following.  Note that although there is a small similarity
205 between this authentication protocol and the cvs protocol, they are
206 separate.
207
208 @table @code
209 @item I LOVE YOU
210 The authentication is successful.  The client proceeds with the cvs
211 protocol itself.
212
213 @item I HATE YOU
214 The authentication fails.  After sending this response, the server may
215 close the connection.  It is up to the server to decide whether to give
216 this response, which is generic, or a more specific response using
217 @samp{E} and/or @samp{error}.
218
219 @item E @var{text}
220 Provide a message for the user.  After this reponse, the authentication
221 protocol continues with another response.  Typically the server will
222 provide a series of @samp{E} responses followed by @samp{error}.
223 Compatibility note: @sc{cvs} 1.9.10 and older clients will print
224 @code{unrecognized auth response} and @var{text}, and then exit, upon
225 receiving this response.
226
227 @item error @var{code} @var{text}
228 The authentication fails.  After sending this response, the server may
229 close the connection.  The @var{code} is a code describing why it
230 failed, intended for computer consumption.  The only code currently
231 defined is @samp{0} which is nonspecific, but clients must silently
232 treat any unrecognised codes as nonspecific.
233 The @var{text} should be supplied to the
234 user.  Compatibility note: @sc{cvs} 1.9.10 and older clients will print
235 @code{unrecognized auth response} and @var{text}, and then exit, upon
236 receiving this response.
237 Note that @var{text} for this response, or the @var{text} in an @code{E}
238 response, is not designed for machine parsing.  More vigorous use of
239 @var{code}, or future extensions, will be needed to prove a cleaner
240 machine-parseable indication of what the error was.
241 @end table
242
243 @c If you are thinking of putting samp or code around BEGIN AUTH REQUEST
244 @c and friends, watch for overfull hboxes.
245 If the client wishes to merely authenticate without starting the cvs
246 protocol, the procedure is the same, except BEGIN AUTH REQUEST is
247 replaced with BEGIN VERIFICATION REQUEST, END AUTH REQUEST
248 is replaced with END VERIFICATION REQUEST, and upon receipt of
249 I LOVE YOU the connection is closed rather than continuing.
250
251 Another mechanism is GSSAPI authentication.  GSSAPI is a
252 generic interface to security services such as kerberos.  GSSAPI is
253 specified in RFC2078 (GSSAPI version 2) and RFC1508 (GSSAPI version 1);
254 we are not aware of differences between the two which affect the
255 protocol in incompatible ways, so we make no attempt to specify one
256 version or the other.
257 The procedure here is to start with @samp{BEGIN
258 GSSAPI REQUEST}.  GSSAPI authentication information is then exchanged
259 between the client and the server.  Each packet of information consists
260 of a two byte big endian length, followed by that many bytes of data.
261 After the GSSAPI authentication is complete, the server continues with
262 the responses described above (@samp{I LOVE YOU}, etc.).
263
264 @item future possibilities
265 There are a nearly unlimited number of ways to connect and authenticate.
266 One might want to allow access based on IP address (similar to the usual
267 rsh protocol but with different/no restrictions on ports < 1024), to
268 adopt mechanisms such as Pluggable Authentication Modules (PAM), to
269 allow users to run their own servers under their own usernames without
270 root access, or any number of other possibilities.  The way to add
271 future mechanisms, for the most part, should be to continue to use port
272 2401, but to use different strings in place of @samp{BEGIN AUTH
273 REQUEST}.
274 @end table
275
276 @node Password scrambling
277 @chapter Password scrambling algorithm
278
279 The pserver authentication protocol, as described in @ref{Connection and
280 Authentication}, trivially encodes the passwords.  This is only to
281 prevent inadvertent compromise; it provides no protection against even a
282 relatively unsophisticated attacker.  For comparison, HTTP Basic
283 Authentication (as described in RFC2068) uses BASE64 for a similar
284 purpose.  CVS uses its own algorithm, described here.
285
286 The scrambled password starts with @samp{A}, which serves to identify
287 the scrambling algorithm in use.  After that follows a single octet for
288 each character in the password, according to a fixed encoding.  The
289 values are shown here, with the encoded values in decimal.  Control
290 characters, space, and characters outside the invariant ISO 646
291 character set are not shown; such characters are not recommended for use
292 in passwords.  There is a long discussion of character set issues in
293 @ref{Protocol Notes}.
294
295 @example
296         0 111           P 125           p  58
297 ! 120   1  52   A  57   Q  55   a 121   q 113
298 "  53   2  75   B  83   R  54   b 117   r  32
299         3 119   C  43   S  66   c 104   s  90
300         4  49   D  46   T 124   d 101   t  44
301 % 109   5  34   E 102   U 126   e 100   u  98
302 &  72   6  82   F  40   V  59   f  69   v  60
303 ' 108   7  81   G  89   W  47   g  73   w  51
304 (  70   8  95   H  38   X  92   h  99   x  33
305 )  64   9  65   I 103   Y  71   i  63   y  97
306 *  76   : 112   J  45   Z 115   j  94   z  62
307 +  67   ;  86   K  50           k  93
308 , 116   < 118   L  42           l  39
309 -  74   = 110   M 123           m  37
310 .  68   > 122   N  91           n  61
311 /  87   ? 105   O  35   _  56   o  48
312 @end example
313
314 @node Protocol
315 @chapter The CVS client/server protocol
316
317 In the following, @samp{\n} refers to a linefeed and @samp{\t} refers to
318 a horizontal tab; @dfn{requests} are what the client sends and
319 @dfn{responses} are what the server sends.  In general, the connection is
320 governed by the client---the server does not send responses without
321 first receiving requests to do so; see @ref{Response intro} for more
322 details of this convention.
323
324 It is typical, early in the connection, for the client to transmit a
325 @code{Valid-responses} request, containing all the responses it
326 supports, followed by a @code{valid-requests} request, which elicits
327 from the server a @code{Valid-requests} response containing all the
328 requests it understands.  In this way, the client and server each find
329 out what the other supports before exchanging large amounts of data
330 (such as file contents).
331
332 @c Hmm, having 3 sections in this menu makes a certain amount of sense
333 @c but that structure gets lost in the printed manual (not sure about
334 @c HTML).  Perhaps there is a better way.
335 @menu
336
337 General protocol conventions:
338
339 * Entries Lines::                   Transmitting RCS data
340 * File Modes::                      Read, write, execute, and possibly more...
341 * Filenames::                       Conventions regarding filenames
342 * File transmissions::              How file contents are transmitted
343 * Strings::                         Strings in various requests and responses
344 * Dates::                           Times and dates
345
346 The protocol itself:
347
348 * Request intro::                   General conventions relating to requests
349 * Requests::                        List of requests
350 * Response intro::                  General conventions relating to responses
351 * Response pathnames::              The "pathname" in responses
352 * Responses::                       List of responses
353 * Text tags::                       More details about the MT response
354
355 An example session, and some further observations:
356
357 * Example::                         A conversation between client and server
358 * Requirements::                    Things not to omit from an implementation
359 * Obsolete::                        Former protocol features
360 @end menu
361
362 @node Entries Lines
363 @section Entries Lines
364
365 Entries lines are transmitted as:
366
367 @example
368 / @var{name} / @var{version} / @var{conflict} / @var{options} / @var{tag_or_date}
369 @end example
370
371 @var{tag_or_date} is either @samp{T} @var{tag} or @samp{D} @var{date}
372 or empty.  If it is followed by a slash, anything after the slash
373 shall be silently ignored.
374
375 @var{version} can be empty, or start with @samp{0} or @samp{-}, for no
376 user file, new user file, or user file to be removed, respectively.
377
378 @c FIXME: should distinguish sender and receiver behavior here; the
379 @c "anything else" and "does not start with" are intended for future
380 @c expansion, and we should specify a sender behavior.
381 @var{conflict}, if it starts with @samp{+}, indicates that the file had
382 conflicts in it.  The rest of @var{conflict} is @samp{=} if the
383 timestamp matches the file, or anything else if it doesn't.  If
384 @var{conflict} does not start with a @samp{+}, it is silently ignored.
385
386 @var{options} signifies the keyword expansion options (for example
387 @samp{-ko}).  In an @code{Entry} request, this indicates the options
388 that were specified with the file from the previous file updating
389 response (@pxref{Response intro}, for a list of file updating
390 responses); if the client is specifying the @samp{-k} or @samp{-A}
391 option to @code{update}, then it is the server which figures out what
392 overrides what.
393
394 @node File Modes
395 @section File Modes
396
397 A mode is any number of repetitions of
398
399 @example
400 @var{mode-type} = @var{data}
401 @end example
402
403 separated by @samp{,}.
404
405 @var{mode-type} is an identifier composed of alphanumeric characters.
406 Currently specified: @samp{u} for user, @samp{g} for group, @samp{o}
407 for other (see below for discussion of whether these have their POSIX
408 meaning or are more loose).  Unrecognised values of @var{mode-type}
409 are silently ignored.
410
411 @var{data} consists of any data not containing @samp{,}, @samp{\0} or
412 @samp{\n}.  For @samp{u}, @samp{g}, and @samp{o} mode types, data
413 consists of alphanumeric characters, where @samp{r} means read, @samp{w}
414 means write, @samp{x} means execute, and unrecognised letters are
415 silently ignored.
416
417 The two most obvious ways in which the mode matters are: (1) is it
418 writeable?  This is used by the developer communication features, and
419 is implemented even on OS/2 (and could be implemented on DOS), whose
420 notion of mode is limited to a readonly bit. (2) is it executable?
421 Unix CVS users need CVS to store this setting (for shell scripts and
422 the like).  The current CVS implementation on unix does a little bit
423 more than just maintain these two settings, but it doesn't really have
424 a nice general facility to store or version control the mode, even on
425 unix, much less across operating systems with diverse protection
426 features.  So all the ins and outs of what the mode means across
427 operating systems haven't really been worked out (e.g. should the VMS
428 port use ACLs to get POSIX semantics for groups?).
429
430 @node Filenames
431 @section Conventions regarding transmission of file names
432
433 In most contexts, @samp{/} is used to separate directory and file
434 names in filenames, and any use of other conventions (for example,
435 that the user might type on the command line) is converted to that
436 form.  The only exceptions might be a few cases in which the server
437 provides a magic cookie which the client then repeats verbatim, but as
438 the server has not yet been ported beyond unix, the two rules provide
439 the same answer (and what to do if future server ports are operating
440 on a repository like e:/foo or CVS_ROOT:[FOO.BAR] has not been
441 carefully thought out).
442
443 Characters outside the invariant ISO 646 character set should be avoided
444 in filenames.  This restriction may need to be relaxed to allow for
445 characters such as @samp{[} and @samp{]} (see above about non-unix
446 servers); this has not been carefully considered (and currently
447 implementations probably use whatever character sets that the operating
448 systems they are running on allow, and/or that users specify).  Of
449 course the most portable practice is to restrict oneself further, to the
450 POSIX portable filename character set as specified in POSIX.1.
451
452 @node File transmissions
453 @section File transmissions
454
455 File contents (noted below as @var{file transmission}) can be sent in
456 one of two forms.  The simpler form is a number of bytes, followed by a
457 linefeed, followed by the specified number of bytes of file contents.
458 These are the entire contents of the specified file.  Second, if both
459 client and server support @samp{gzip-file-contents}, a @samp{z} may
460 precede the length, and the `file contents' sent are actually compressed
461 with @samp{gzip} (RFC1952/1951) compression.  The length specified is
462 that of the compressed version of the file.
463
464 In neither case are the file content followed by any additional data.
465 The transmission of a file will end with a linefeed iff that file (or its
466 compressed form) ends with a linefeed.
467
468 The encoding of file contents depends on the value for the @samp{-k}
469 option.  If the file is binary (as specified by the @samp{-kb} option in
470 the appropriate place), then it is just a certain number of octets, and
471 the protocol contributes nothing towards determining the encoding (using
472 the file name is one widespread, if not universally popular, mechanism).
473 If the file is text (not binary), then the file is sent as a series of
474 lines, separated by linefeeds.  If the keyword expansion is set to
475 something other than @samp{-ko}, then it is expected that the file
476 conform to the RCS expectations regarding keyword expansion---in
477 particular, that it is in a character set such as ASCII in which 0x24 is
478 a dollar sign (@samp{$}).
479
480 @node Strings
481 @section Strings
482
483 In various contexts, for example the @code{Argument} request and the
484 @code{M} response, one transmits what is essentially an arbitrary
485 string.  Often this will have been supplied by the user (for example,
486 the @samp{-m} option to the @code{ci} request will show up in the
487 @code{LOGM} response).  The protocol has no mechanism to specify the
488 character set of such strings; it would have been, initially, fairly
489 safe to stick to the invariant ISO 646 character set but the existing
490 practice is probably to just transmit whatever the user specifies,
491 and hope that everyone involved agrees which character set is in use,
492 or sticks to a common subset. In modern times, UTF-8 should be used.
493
494 @node Dates
495 @section Dates
496
497 The protocol contains times and dates in various places.
498
499 For the @samp{-D} option to the @code{annotate}, @code{co}, @code{diff},
500 @code{export}, @code{history}, @code{rannotate}, @code{rdiff},
501 @code{rtag}, @code{tag},
502 and @code{update} requests, the server should support two formats:
503
504 @example
505 26 May 1997 13:01:40 -0000  ; @r{RFC 822 as modified by RFC 1123}
506 5/26/1997 13:01:40 GMT    ; @r{traditional}
507 @end example
508
509 The former format is preferred; the latter however is sent by the CVS
510 command line client (versions 1.5 through at least 1.9).
511
512 For the @samp{-d} option to the @code{log} and @code{rlog} requests,
513 servers should at
514 least support RFC 822/1123 format.  Clients are encouraged to use this
515 format too (the command line CVS client, version 1.10 and older, just passed
516 along the date format specified by the user, however).
517
518 The @code{Mod-time} response and @code{Checkin-time} request use RFC
519 822/1123 format (see the descriptions of that response and request for
520 details).
521
522 For @code{Notify}, see the description of that request.
523
524 @node Request intro
525 @section Request intro
526
527 By convention, requests which begin with a capital letter do not elicit
528 a response from the server, while all others do -- save one.  The
529 exception is @samp{gzip-file-contents}.  Unrecognised requests will
530 always elicit a response from the server, even if that request begins
531 with a capital letter.
532
533 The term @dfn{command} means a request which expects a response (except
534 @code{valid-requests}).  The general model is that the client transmits
535 a great number of requests, but nothing happens until the very end when
536 the client transmits a command.  Although the intention is that
537 transmitting several commands in one connection should be legal,
538 existing servers probably have some bugs with some combinations of more
539 than one command, and so clients may find it necessary to make several
540 connections in some cases.  This should be thought of as a workaround
541 rather than a desired attribute of the protocol.
542
543 @node Requests
544 @section Requests
545
546 Here are the requests:
547
548 @table @code
549 @item Root @var{pathname} \n
550 Response expected: no.  Tell the server which @code{CVSROOT} to use.
551 Note that @var{pathname} is a local directory and @emph{not} a fully
552 qualified @code{CVSROOT} variable.  @var{pathname} must
553 already exist; if creating a new root, use the @code{init} request, not
554 @code{Root}.  @var{pathname} does not include the hostname of the
555 server, how to access the server, etc.; by the time the CVS protocol is
556 in use, connection, authentication, etc., are already taken care of.
557
558 The @code{Root} request must be sent only once, and it must be sent
559 before any requests other than @code{Valid-responses},
560 @code{valid-requests}, @code{UseUnchanged}, @code{Set},
561 @code{Global_option}, @code{init}, @code{noop}, or @code{version}.
562
563 @item Valid-responses @var{request-list} \n
564 Response expected: no.
565 Tell the server what responses the client will accept.
566 request-list is a space separated list of tokens.
567 The @code{Root} request need not have been previously sent.
568
569 @item valid-requests \n
570 Response expected: yes.
571 Ask the server to send back a @code{Valid-requests} response.
572 The @code{Root} request need not have been previously sent.
573
574 @item Command-prep @var{command} \n
575 Response expected: yes.
576 Notify the server of the command that we are leading up to.  Intended to allow
577 the server to send a redirect for write operations.  Requires either an
578 @code{ok} or @code{Redirect} respnose.
579
580 @item Referrer @var{CVSROOT} \n
581 Response expected: no.
582 Notify a primary server of a server which referred us.  Intended to allow
583 a primary (write) server to update the read-only mirror a client is using
584 for reads to minimise races on any subsequent updates from the client.
585
586 @item Directory @var{local-directory} \n
587 @itemx Relative-directory @var{local-directory} \n
588 Additional data: @var{repository} \n.  Response expected: no.
589 Tell the server what directory to use.
590
591 The @var{repository} should be a directory name from a previous server
592 response and may be specified either relative to the @var{pathname} provided
593 with the @code{Root} request or absolute.  Relative or absolute, it must
594 specify a path within @var{pathname}.
595
596 Prior to @sc{cvs} version @strong{FIXME - release number 1.12.10?},
597 @var{repository} had to be absolute and @code{Relative-directory} was not a
598 valid request.  The @code{Relative-directory} request is synonymous with
599 @code{Directory} and is provided to alert modern clients that a relative
600 @var{repository} is acceptable.
601
602 Note that this both gives a default for @code{Entry} and @code{Modified} and
603 also for @code{ci} and the other commands; normal usage is to send 
604 @code{Directory} for each directory in which there will be an
605 @code{Entry} or @code{Modified}, and then a final @code{Directory}
606 for the original directory, then the command.
607 The @var{local-directory} is relative to
608 the top level at which the command is occurring (i.e. the last
609 @code{Directory} which is sent before the command);
610 to indicate that top level, @samp{.} should be sent for
611 @var{local-directory}.
612
613 Here is an example of where a client gets @var{repository} and
614 @var{local-directory}.  Suppose that there is a module defined by
615
616 @example
617 moddir 1dir
618 @end example
619
620 That is, one can check out @code{moddir} and it will take @code{1dir} in
621 the repository and check it out to @code{moddir} in the working
622 directory.  Then an initial check out could proceed like this:
623
624 @example
625 C: Root /home/kingdon/zwork/cvsroot
626 . . .
627 C: Argument moddir
628 C: Directory .
629 C: .
630 C: co
631 S: Clear-sticky moddir/
632 S: 1dir/
633 . . .
634 S: ok
635 @end example
636
637 In this example the response shown is @code{Clear-sticky}, but it could
638 be another response instead.  Note that it returns two pathnames.
639 The first one, @file{moddir/}, indicates the working
640 directory to check out into.  The second one, ending in @file{1dir/},
641 indicates the directory to pass back to the server in a subsequent
642 @code{Directory} request.  For example, a subsequent @code{update}
643 request might look like:
644
645 @example
646 C: Directory moddir
647 C: 1dir
648 . . .
649 C: update
650 @end example
651
652 For a given @var{local-directory}, the repository will be the same for
653 each of the responses, so one can use the repository from whichever
654 response is most convenient.  Typically a client will store the
655 repository along with the sources for each @var{local-directory}, use
656 that same setting whenever operating on that @var{local-directory}, and
657 not update the setting as long as the @var{local-directory} exists.
658
659 A client is free to rename a @var{local-directory} at any time (for
660 example, in response to an explicit user request).  While it is true
661 that the server supplies a @var{local-directory} to the client, as noted
662 above, this is only the default place to put the directory.  Of course,
663 the various @code{Directory} requests for a single command (for example,
664 @code{update} or @code{ci} request) should name a particular directory
665 with the same @var{local-directory}.
666
667 Each @code{Directory} request specifies a brand-new
668 @var{local-directory} and @var{repository}; that is,
669 @var{local-directory} and @var{repository} are never relative to paths
670 specified in any previous @code{Directory} request.
671
672 Here's a more complex example, in which we request an update of a
673 working directory which has been checked out from multiple places in the
674 repository.
675
676 @example
677 C: Argument dir1
678 C: Directory dir1
679 C: mod1
680 . . .
681 C: Argument dir2
682 C: Directory dir2
683 C: mod2
684 . . .
685 C: Argument dir3
686 C: Directory dir3/subdir3
687 C: mod3
688 . . .
689 C: update
690 @end example
691
692 While directories @code{dir1} and @code{dir2} will be handled in similar
693 fashion to the other examples given above, @code{dir3} is slightly
694 different from the server's standpoint.  Notice that module @code{mod3}
695 is actually checked out into @code{dir3/subdir3}, meaning that directory
696 @code{dir3} is either empty or does not contain data checked out from
697 this repository.  
698
699 The above example will work correctly in @sc{cvs} 1.10.1 and later.  The
700 server will descend the tree starting from all directories mentioned in
701 @code{Argument} requests and update those directories specifically
702 mentioned in @code{Directory} requests.
703
704 Previous versions of @sc{cvs} (1.10 and earlier) do not behave the same
705 way.  While the descent of the tree begins at all directories mentioned
706 in @code{Argument} requests, descent into subdirectories only occurs if
707 a directory has been mentioned in a @code{Directory} request.
708 Therefore, the above example would succeed in updating @code{dir1} and
709 @code{dir2}, but would skip @code{dir3} because that directory was not
710 specifically mentioned in a @code{Directory} request.  A functional
711 version of the above that would run on a 1.10 or earlier server is as
712 follows:
713
714 @example
715 C: Argument dir1
716 C: Directory dir1
717 C: mod1
718 . . .
719 C: Argument dir2
720 C: Directory dir2
721 C: mod2
722 . . .
723 C: Argument dir3
724 C: Directory dir3
725 C: .
726 . . .
727 C: Directory dir3/subdir3
728 C: mod3
729 . . .
730 C: update
731 @end example
732
733 Note the extra @code{Directory dir3} request.  It might be better to use
734 @code{Emptydir} as the repository for the @code{dir3} directory, but the
735 above will certainly work.
736
737 One more peculiarity of the 1.10 and earlier protocol is the ordering of
738 @code{Directory} arguments.  In order for a subdirectory to be
739 registered correctly for descent by the recursion processor, its parent
740 must be sent first.  For example, the following would not work to update
741 @code{dir3/subdir3}:
742
743 @example
744 . . .
745 C: Argument dir3
746 C: Directory dir3/subdir3
747 C: mod3
748 . . .
749 C: Directory dir3
750 C: .
751 . . .
752 C: update
753 @end example
754
755 The implementation of the server in 1.10 and earlier writes the
756 administration files for a given directory at the time of the
757 @code{Directory} request.  It also tries to register the directory with
758 its parent to mark it for recursion.  In the above example, at the time
759 @code{dir3/subdir3} is created, the physical directory for @code{dir3}
760 will be created on disk, but the administration files will not have been
761 created.  Therefore, when the server tries to register
762 @code{dir3/subdir3} for recursion, the operation will silently fail
763 because the administration files do not yet exist for @code{dir3}.
764
765 @item Max-dotdot @var{level} \n
766 Response expected: no.
767 Tell the server that @var{level} levels of directories above the
768 directory which @code{Directory} requests are relative to will be
769 needed.  For example, if the client is planning to use a
770 @code{Directory} request for @file{../../foo}, it must send a
771 @code{Max-dotdot} request with a @var{level} of at least 2.
772 @code{Max-dotdot} must be sent before the first @code{Directory}
773 request.
774
775 @item Static-directory \n
776 Response expected: no.  Tell the server that the directory most recently
777 specified with @code{Directory} should not have
778 additional files checked out unless explicitly requested.  The client
779 sends this if the @code{Entries.Static} flag is set, which is controlled
780 by the @code{Set-static-directory} and @code{Clear-static-directory}
781 responses.
782
783 @item Sticky @var{tagspec} \n
784 Response expected: no.  Tell the server that the directory most recently
785 specified with @code{Directory} has a sticky tag or date @var{tagspec}.
786 The first character of @var{tagspec} is @samp{T} for a tag, @samp{D}
787 for a date, or some other character supplied by a Set-sticky response
788 from a previous request to the server.  The remainder of @var{tagspec}
789 contains the actual tag or date, again as supplied by Set-sticky.
790
791 The server should remember @code{Static-directory} and @code{Sticky}
792 requests for a particular directory; the client need not resend them
793 each time it sends a @code{Directory} request for a given directory.
794 However, the server is not obliged to remember them beyond the context
795 of a single command.
796
797 @item Checkin-prog @var{program} \n
798 Response expected: no.  Tell the server that the directory most recently
799 specified with @code{Directory} has a checkin program @var{program}.
800 Such a program would have been previously set with the
801 @code{Set-checkin-prog} response.
802
803 @item Update-prog @var{program} \n
804 Response expected: no.  Tell the server that the directory most recently
805 specified with @code{Directory} has an update program @var{program}.
806 Such a program would have been previously set with the
807 @code{Set-update-prog} response.
808
809 @item Entry @var{entry-line} \n
810 Response expected: no.  Tell the server what version of a file is on the
811 local machine.  The name in @var{entry-line} is a name relative to the
812 directory most recently specified with @code{Directory}.  If the user
813 is operating on only some files in a directory, @code{Entry} requests
814 for only those files need be included.  If an @code{Entry} request is
815 sent without @code{Modified}, @code{Is-modified}, or @code{Unchanged},
816 it means the file is
817 lost (does not exist in the working directory).  If both @code{Entry}
818 and one of @code{Modified}, @code{Is-modified}, or @code{Unchanged} are
819 sent for the same file, @code{Entry} must be sent first.  For a
820 given file, one can send @code{Modified}, @code{Is-modified}, or
821 @code{Unchanged}, but not more than one of these three.
822
823 @item Kopt @var{option} \n
824 This indicates to the server which keyword expansion options to use for
825 the file specified by the next @code{Modified} or @code{Is-modified}
826 request (for example @samp{-kb} for a binary file).  This is similar to
827 @code{Entry}, but is used for a file for which there is no entries line.
828 Typically this will be a file being added via an @code{add} or
829 @code{import} request.  The client may not send both @code{Kopt} and
830 @code{Entry} for the same file.
831
832 @item Checkin-time @var{time} \n
833 For the file specified by the next @code{Modified} request, use
834 @var{time} as the time of the checkin.  The @var{time} is in the format
835 specified by RFC822 as modified by RFC1123.  The client may specify any
836 timezone it chooses; servers will want to convert that to their own
837 timezone as appropriate.  An example of this format is:
838
839 @example
840 26 May 1997 13:01:40 -0400
841 @end example
842
843 There is no requirement that the client and server clocks be
844 synchronised.  The client just sends its recommendation for a timestamp
845 (based on file timestamps or whatever), and the server should just believe
846 it (this means that the time might be in the future, for example).
847
848 Note that this is not a general-purpose way to tell the server about the
849 timestamp of a file; that would be a separate request (if there are
850 servers which can maintain timestamp and time of checkin separately).
851
852 This request should affect the @code{import} request, and may optionally
853 affect the @code{ci} request or other relevant requests if any.
854
855 @item Modified @var{filename} \n
856 Response expected: no.  Additional data: mode, \n, file transmission.
857 Send the server a copy of one locally modified file.  @var{filename} is
858 a file within the most recent directory sent with @code{Directory}; it
859 must not contain @samp{/}.  If
860 the user is operating on only some files in a directory, only those
861 files need to be included.  This can also be sent without @code{Entry},
862 if there is no entry for the file.
863
864 @item Is-modified @var{filename} \n
865 Response expected: no.  Additional data: none.  Like @code{Modified},
866 but used if the server only needs
867 to know whether the file is modified, not the contents.
868
869 The commands which can take @code{Is-modified} instead of
870 @code{Modified} with no known change in behavior are: @code{admin},
871 @code{diff} (if and only if two @samp{-r} or @samp{-D} options are
872 specified), @code{watch-on}, @code{watch-off}, @code{watch-add},
873 @code{watch-remove}, @code{watchers}, @code{editors},
874 @code{log}, and @code{annotate}.
875
876 For the @code{status} command, one can send @code{Is-modified} but if
877 the client is using imperfect mechanisms such as timestamps to determine
878 whether to consider a file modified, then the behavior will be
879 different.  That is, if one sends @code{Modified}, then the server will
880 actually compare the contents of the file sent and the one it derives
881 from to determine whether the file is genuinely modified.  But if one
882 sends @code{Is-modified}, then the server takes the client's word for
883 it.  A similar situation exists for @code{tag}, if the @samp{-c} option
884 is specified.
885
886 Commands for which @code{Modified} is necessary are @code{co},
887 @code{ci}, @code{update}, and @code{import}.
888
889 Commands which do not need to inform the server about a working
890 directory, and thus should not be sending either @code{Modified} or
891 @code{Is-modified}: @code{rdiff}, @code{rtag}, @code{history},
892 @code{init}, and @code{release}.
893
894 Commands for which further investigation is warranted are:
895 @code{remove}, @code{add}, and @code{export}.  Pending such
896 investigation, the more conservative course of action is to stick to
897 @code{Modified}.
898
899 @item Unchanged @var{filename} \n
900 Response expected: no.  Tell the server that @var{filename} has not been
901 modified in the checked out directory.  The @var{filename} is
902 a file within the most recent directory sent with @code{Directory}; it
903 must not contain @samp{/}.
904
905 @item UseUnchanged \n
906 Response expected: no.  To specify the version of the protocol described
907 in this document, servers must support this request (although it need
908 not do anything) and clients must issue it.
909 The @code{Root} request need not have been previously sent.
910
911 @item Notify @var{filename} \n
912 Response expected: no.
913 Tell the server that an @code{edit} or @code{unedit} command has taken
914 place.  The server needs to send a @code{Notified} response, but such
915 response is deferred until the next time that the server is sending
916 responses.
917 The @var{filename} is a file within the most recent directory sent with
918 @code{Directory}; it must not contain @samp{/}.
919 Additional data:
920 @example
921 @var{notification-type} \t @var{time} \t @var{clienthost} \t
922 @var{working-dir} \t @var{watches} \n
923 @end example
924 where @var{notification-type} is @samp{E} for edit, @samp{U} for
925 unedit, undefined behavior if @samp{C}, and all other letters should be
926 silently ignored for future expansion.
927 @var{time} is the time at which the edit or unedit took place, in a
928 user-readable format of the client's choice (the server should treat the
929 time as an opaque string rather than interpreting it).
930 @c Might be useful to specify a format, but I don't know if we want to
931 @c specify the status quo (ISO C asctime() format plus timezone) without
932 @c offering the option of ISO8601 and/or RFC822/1123 (see cvs.texinfo
933 @c for much much more on date formats).
934 @var{clienthost} is the name of the host on which the edit or unedit
935 took place, and @var{working-dir} is the pathname of the working
936 directory where the edit or unedit took place.  @var{watches} are the
937 temporary watches, zero or more of the following characters in the
938 following order: @samp{E} for edit, @samp{U} for unedit, @samp{C} for
939 commit, and all other letters should be silently ignored for future
940 expansion.  If @var{notification-type} is @samp{E} the temporary watches
941 are set; if it is @samp{U} they are cleared.
942 If @var{watches} is followed by \t then the
943 \t and the rest of the line should be ignored, for future expansion.
944
945 The @var{time}, @var{clienthost}, and @var{working-dir} fields may not
946 contain the characters @samp{+}, @samp{,}, @samp{>}, @samp{;}, or @samp{=}.
947
948 Note that a client may be capable of performing an @code{edit} or
949 @code{unedit} operation without connecting to the server at that time,
950 and instead connecting to the server when it is convenient (for example,
951 when a laptop is on the net again) to send the @code{Notify} requests.
952 Even if a client is capable of deferring notifications, it should
953 attempt to send them immediately (one can send @code{Notify} requests
954 together with a @code{noop} request, for example), unless perhaps if
955 it can know that a connection would be impossible.
956
957 @item Questionable @var{filename} \n
958 Response expected: no.  Additional data: no.  Tell the server to check
959 whether @var{filename} should be ignored, and if not, next time the
960 server sends responses, send (in a @code{M} response) @samp{?} followed
961 by the directory and filename.  @var{filename} must not contain
962 @samp{/}; it needs to be a file in the directory named by the most
963 recent @code{Directory} request.
964 @c FIXME: the bit about not containing / is true of most of the
965 @c requests, but isn't documented and should be.
966
967 @item Case \n
968 Response expected: no.  Tell the server that filenames should be matched
969 in a case-insensitive fashion.  Note that this is not the primary
970 mechanism for achieving case-insensitivity; for the most part the client
971 keeps track of the case which the server wants to use and takes care to
972 always use that case regardless of what the user specifies.  For example
973 the filenames given in @code{Entry} and @code{Modified} requests for the
974 same file must match in case regardless of whether the @code{Case}
975 request is sent.  The latter mechanism is more general (it could also be
976 used for 8.3 filenames, VMS filenames with more than one @samp{.}, and
977 any other situation in which there is a predictable mapping between
978 filenames in the working directory and filenames in the protocol), but
979 there are some situations it cannot handle (ignore patterns, or
980 situations where the user specifies a filename and the client does not
981 know about that file).
982
983 Though this request will be supported into the forseeable future, it has been
984 the source of numerous bug reports in the past due to the complexity of testing
985 this functionality via the test suite and client developers are encouraged not
986 to use it.  Instead, please consider munging conflicting names and maintaining
987 a map for communicating with the server.  For example, suppose the server sends
988 files @file{case}, @file{CASE}, and @file{CaSe}.  The client could write all
989 three files to names such as, @file{case}, @file{case_prefix_case}, and
990 @file{case_prefix_2_case} and maintain a mapping between the file names in, for
991 instance a new @file{CVS/Map} file.
992
993 @item Argument @var{text} \n
994 Response expected: no.
995 Save argument for use in a subsequent command.  Arguments
996 accumulate until an argument-using command is given, at which point
997 they are forgotten.
998
999 @item Argumentx @var{text} \n
1000 Response expected: no.  Append \n followed by text to the current
1001 argument being saved.
1002
1003 @item Global_option @var{option} \n
1004 Response expected: no.
1005 Transmit one of the global options @samp{-q}, @samp{-Q}, @samp{-l},
1006 @samp{-t}, @samp{-r}, or @samp{-n}.  @var{option} must be one of those
1007 strings, no variations (such as combining of options) are allowed.  For
1008 graceful handling of @code{valid-requests}, it is probably better to
1009 make new global options separate requests, rather than trying to add
1010 them to this request.
1011 The @code{Root} request need not have been previously sent.
1012
1013 @item Gzip-stream @var{level} \n
1014 Response expected: no.
1015 Use zlib (RFC 1950/1951) compression to compress all further communication
1016 between the client and the server.  As of @sc{cvs} 1.12.13, this request needs
1017 to be sent as the first non-rootless request if the server is configured
1018 with compression level restrictions and @var{level} is outside the restricted
1019 range.  After this request is sent, all further communication must be
1020 compressed.  All further data received from the server will also be
1021 compressed.  The @var{level} argument suggests to the server the level of
1022 compression that it should apply; it should be an integer between 0 and 9,
1023 inclusive, where @samp{0} means no compression and higher numbers indicate more
1024 compression.
1025
1026 @item Kerberos-encrypt \n
1027 Response expected: no.
1028 Use Kerberos encryption to encrypt all further communication between the
1029 client and the server.  This will only work if the connection was made
1030 over Kerberos in the first place.  If both the @code{Gzip-stream} and
1031 the @code{Kerberos-encrypt} requests are used, the
1032 @code{Kerberos-encrypt} request should be used first.  This will make
1033 the client and server encrypt the compressed data, as opposed to
1034 compressing the encrypted data.  Encrypted data is generally
1035 incompressible.
1036
1037 Note that this request does not fully prevent an attacker from hijacking
1038 the connection, in the sense that it does not prevent hijacking the
1039 connection between the initial authentication and the
1040 @code{Kerberos-encrypt} request.
1041
1042 @item Gssapi-encrypt \n
1043 Response expected: no.
1044 Use GSSAPI encryption to encrypt all further communication between the
1045 client and the server.  This will only work if the connection was made
1046 over GSSAPI in the first place.  See @code{Kerberos-encrypt}, above, for
1047 the relation between @code{Gssapi-encrypt} and @code{Gzip-stream}.
1048
1049 Note that this request does not fully prevent an attacker from hijacking
1050 the connection, in the sense that it does not prevent hijacking the
1051 connection between the initial authentication and the
1052 @code{Gssapi-encrypt} request.
1053
1054 @item Gssapi-authenticate \n
1055 Response expected: no.
1056 Use GSSAPI authentication to authenticate all further communication
1057 between the client and the server.  This will only work if the
1058 connection was made over GSSAPI in the first place.  Encrypted data is
1059 automatically authenticated, so using both @code{Gssapi-authenticate}
1060 and @code{Gssapi-encrypt} has no effect beyond that of
1061 @code{Gssapi-encrypt}.  Unlike encrypted data, it is reasonable to
1062 compress authenticated data.
1063
1064 Note that this request does not fully prevent an attacker from hijacking
1065 the connection, in the sense that it does not prevent hijacking the
1066 connection between the initial authentication and the
1067 @code{Gssapi-authenticate} request.
1068
1069 @item Set @var{variable}=@var{value} \n
1070 Response expected: no.
1071 Set a user variable @var{variable} to @var{value}.
1072 The @code{Root} request need not have been previously sent.
1073
1074 @item Hostname @var{hostname} \n
1075 Response expected: no.  Set the client hostname for an upcoming @code{edit}
1076 request.
1077
1078 @item LocalDir @var{hostname} \n
1079 Response expected: no.  Set the local client directory name for an upcoming
1080 @code{edit} request.
1081
1082 @item expand-modules \n
1083 Response expected: yes.  Expand the modules which are specified in the
1084 arguments.  Returns the data in @code{Module-expansion} responses.  Note
1085 that the server can assume that this is checkout or export, not rtag or
1086 rdiff; the latter do not access the working directory and thus have no
1087 need to expand modules on the client side.
1088
1089 Expand may not be the best word for what this request does.  It does not
1090 necessarily tell you all the files contained in a module, for example.
1091 Basically it is a way of telling you which working directories the
1092 server needs to know about in order to handle a checkout of the
1093 specified modules.
1094
1095 For example, suppose that the server has a module defined by
1096
1097 @example
1098 aliasmodule -a 1dir
1099 @end example
1100
1101 That is, one can check out @code{aliasmodule} and it will take
1102 @code{1dir} in the repository and check it out to @code{1dir} in the
1103 working directory.  Now suppose the client already has this module
1104 checked out and is planning on using the @code{co} request to update it.
1105 Without using @code{expand-modules}, the client would have two bad
1106 choices: it could either send information about @emph{all} working
1107 directories under the current directory, which could be unnecessarily
1108 slow, or it could be ignorant of the fact that @code{aliasmodule} stands
1109 for @code{1dir}, and neglect to send information for @code{1dir}, which
1110 would lead to incorrect operation.
1111 @c Those don't really seem like the only two options.  I mean, what
1112 @c about keeping track of the correspondence from when we first checked
1113 @c out a fresh directory?  Not that the CVS client does this, or that
1114 @c I've really thought about whether it would be a good idea...
1115
1116 With @code{expand-modules}, the client would first ask for the module to
1117 be expanded:
1118
1119 @example
1120 C: Root /home/kingdon/zwork/cvsroot
1121 . . .
1122 C: Argument aliasmodule
1123 C: Directory .
1124 C: .
1125 C: expand-modules
1126 S: Module-expansion 1dir
1127 S: ok
1128 @end example
1129
1130 and then it knows to check the @file{1dir} directory and send
1131 requests such as @code{Entry} and @code{Modified} for the files in that
1132 directory.
1133
1134 @item ci \n
1135 @itemx diff \n
1136 @itemx list \n
1137 @itemx tag \n
1138 @itemx status \n
1139 @itemx admin \n
1140 @itemx history \n
1141 @itemx watchers \n
1142 @itemx editors \n
1143 @itemx annotate \n
1144 Response expected: yes.  Actually do a cvs command.  This uses any
1145 previous @code{Argument}, @code{Directory}, @code{Entry}, or
1146 @code{Modified} requests, if they have been sent.  The
1147 last @code{Directory} sent specifies the working directory at the time
1148 of the operation.  No provision is made for any input from the user.
1149 This means that @code{ci} must use a @code{-m} argument if it wants to
1150 specify a log message.
1151
1152 @item log \n
1153 Response expected: yes.  Show information for past revisions.  This uses
1154 any previous @code{Directory}, @code{Entry}, or @code{Modified}
1155 requests, if they have been sent.  The last @code{Directory} sent
1156 specifies the working directory at the time of the operation.  Also uses
1157 previous @code{Argument}'s of which the canonical forms are the
1158 following (@sc{cvs} 1.10 and older clients sent what the user specified,
1159 but clients are encouraged to use the canonical forms and other forms
1160 are deprecated):
1161
1162 @table @code
1163 @item -b, -h, -l, -N, -R, -t
1164 These options go by themselves, one option per @code{Argument} request.
1165
1166 @item -d @var{date1}<@var{date2}
1167 Select revisions between @var{date1} and @var{date2}.  Either date
1168 may be omitted in which case there is no date limit at that end of the
1169 range (clients may specify dates such as 1 Jan 1970 or 1 Jan 2038 for
1170 similar purposes but this is problematic as it makes assumptions about
1171 what dates the server supports).  Dates are in RFC822/1123 format.  The
1172 @samp{-d} is one @code{Argument} request and the date range is a second
1173 one.
1174
1175 @item -d @var{date1}<=@var{date2}
1176 Likewise but compare dates for equality.
1177
1178 @item -d @var{singledate}
1179 Select the single, latest revision dated @var{singledate} or earlier.
1180
1181 To include several date ranges and/or singledates, repeat the @samp{-d}
1182 option as many times as necessary.
1183
1184 @item -r@var{rev1}:@var{rev2}
1185 @itemx -r@var{branch}
1186 @itemx -r@var{branch}.
1187 @itemx -r
1188 Specify revisions (note that @var{rev1} or @var{rev2} can be omitted, or
1189 can refer to branches).  Send both the @samp{-r} and the revision
1190 information in a single @code{Argument} request.  To include several
1191 revision selections, repeat the @samp{-r} option.
1192
1193 @item -s @var{state}
1194 @itemx -w
1195 @itemx -w@var{login}
1196 Select on states or users.  To include more than one state or user,
1197 repeat the option.  Send the @samp{-s} option as a separate argument
1198 from the state being selected.  Send the @samp{-w} option as part of the
1199 same argument as the user being selected.
1200 @end table
1201
1202 @item co \n
1203 Response expected: yes.  Get files from the repository.  This uses any
1204 previous @code{Argument}, @code{Directory}, @code{Entry}, or
1205 @code{Modified} requests, if they have been sent.  Arguments to this
1206 command are module names; the client cannot know what directories they
1207 correspond to except by (1) just sending the @code{co} request, and then
1208 seeing what directory names the server sends back in its responses, and
1209 (2) the @code{expand-modules} request.
1210
1211 @item export \n
1212 Response expected: yes.  Get files from the repository.  This uses any
1213 previous @code{Argument}, @code{Directory}, @code{Entry}, or
1214 @code{Modified} requests, if they have been sent.  Arguments to this
1215 command are module names, as described for the @code{co} request.  The
1216 intention behind this command is that a client can get sources from a
1217 server without storing CVS information about those sources.  That is, a
1218 client probably should not count on being able to take the entries line
1219 returned in the @code{Created} response from an @code{export} request
1220 and send it in a future @code{Entry} request.  Note that the entries
1221 line in the @code{Created} response must indicate whether the file is
1222 binary or text, so the client can create it correctly.
1223
1224 @item ls \n
1225 @itemx rannotate \n
1226 @itemx rdiff \n
1227 @itemx rlist \n
1228 @itemx rlog \n
1229 @itemx rtag \n
1230 Response expected: yes.  Actually do a cvs command.  This uses any
1231 previous @code{Argument} requests, if they have been sent.  The client
1232 should not send @code{Directory}, @code{Entry}, or @code{Modified}
1233 requests for these commands; they are not used.  Arguments to these
1234 commands are module names, as described for @code{co}.  @code{ls} is a
1235 synonym for @code{rlist}, for compatibility with CVSNT.
1236
1237 @item init @var{root-name} \n
1238 Response expected: yes.  If it doesn't already exist, create a @sc{cvs}
1239 repository @var{root-name}.  Note that @var{root-name} is a local
1240 directory and @emph{not} a fully qualified @code{CVSROOT} variable.
1241 The @code{Root} request need not have been previously sent.
1242
1243 @item suck \n
1244 Response expected: yes.
1245 Actually do a @code{cvs suck} command.
1246 This uses a previous @code{Argument} request (only one, because the
1247 @code{cvs suck} CLI command takes only one).
1248 This is an extension specific to MirBSD, MirPorts and Debian.
1249
1250 @item update \n
1251 Response expected: yes.  Actually do a @code{cvs update} command.  This
1252 uses any previous @code{Argument}, @code{Directory}, @code{Entry},
1253 or @code{Modified} requests, if they have been sent.  The
1254 last @code{Directory} sent specifies the working directory at the time
1255 of the operation.  The @code{-I} option is not used--files which the
1256 client can decide whether to ignore are not mentioned and the client
1257 sends the @code{Questionable} request for others.
1258
1259 @item import \n
1260 Response expected: yes.  Actually do a @code{cvs import} command.  This
1261 uses any previous @code{Argument}, @code{Directory}, @code{Entry}, or
1262 @code{Modified} requests, if they have been sent.  The
1263 last @code{Directory} sent specifies the working directory at the time
1264 of the operation - unlike most commands, the repository field of each
1265 @code{Directory} request is ignored (it merely must point somewhere
1266 within the root).  The files to be imported are sent in @code{Modified}
1267 requests (files which the client knows should be ignored are not sent;
1268 the server must still process the CVSROOT/cvsignore file unless -I ! is
1269 sent).  A log message must have been specified with a @code{-m}
1270 argument.
1271
1272 @item add \n
1273 Response expected: yes.  Add a file or directory.  This uses any
1274 previous @code{Argument}, @code{Directory}, @code{Entry}, or
1275 @code{Modified} requests, if they have been sent.  The
1276 last @code{Directory} sent specifies the working directory at the time
1277 of the operation.
1278
1279 To add a directory, send the directory to be added using
1280 @code{Directory} and @code{Argument} requests.  For example:
1281
1282 @example
1283 C: Root /u/cvsroot
1284 . . .
1285 C: Argument nsdir
1286 C: Directory nsdir
1287 C: 1dir/nsdir
1288 C: Directory .
1289 C: 1dir
1290 C: add
1291 S: M Directory /u/cvsroot/1dir/nsdir put under version control
1292 S: ok
1293 @end example
1294
1295 You will notice that the server does not signal to the client in any
1296 particular way that the directory has been successfully added.  The
1297 client is supposed to just assume that the directory has been added and
1298 update its records accordingly.  Note also that adding a directory is
1299 immediate; it does not wait until a @code{ci} request as files do.
1300
1301 To add a file, send the file to be added using a @code{Modified}
1302 request.  For example:
1303
1304 @example
1305 C: Argument nfile
1306 C: Directory .
1307 C: 1dir
1308 C: Modified nfile
1309 C: u=rw,g=r,o=r
1310 C: 6
1311 C: hello
1312 C: add
1313 S: E cvs server: scheduling file `nfile' for addition
1314 S: Mode u=rw,g=r,o=r
1315 S: Checked-in ./
1316 S: /u/cvsroot/1dir/nfile
1317 S: /nfile/0///
1318 S: E cvs server: use 'cvs commit' to add this file permanently
1319 S: ok
1320 @end example
1321
1322 Note that the file has not been added to the repository; the only effect
1323 of a successful @code{add} request, for a file, is to supply the client
1324 with a new entries line containing @samp{0} to indicate an added file.
1325 In fact, the client probably could perform this operation without
1326 contacting the server, although using @code{add} does cause the server
1327 to perform a few more checks.
1328
1329 The client sends a subsequent @code{ci} to actually add the file to the
1330 repository.
1331
1332 Another quirk of the @code{add} request is that with CVS 1.9 and older,
1333 a pathname specified in
1334 an @code{Argument} request cannot contain @samp{/}.  There is no good
1335 reason for this restriction, and in fact more recent CVS servers don't
1336 have it.
1337 But the way to interoperate with the older servers is to ensure that
1338 all @code{Directory} requests for @code{add} (except those used to add
1339 directories, as described above), use @samp{.} for
1340 @var{local-directory}.  Specifying another string for
1341 @var{local-directory} may not get an error, but it will get you strange
1342 @code{Checked-in} responses from the buggy servers.
1343
1344 @item remove \n
1345 Response expected: yes.  Remove a file.  This uses any
1346 previous @code{Argument}, @code{Directory}, @code{Entry}, or
1347 @code{Modified} requests, if they have been sent.  The
1348 last @code{Directory} sent specifies the working directory at the time
1349 of the operation.
1350
1351 Note that this request does not actually do anything to the repository;
1352 the only effect of a successful @code{remove} request is to supply the
1353 client with a new entries line containing @samp{-} to indicate a removed
1354 file.  In fact, the client probably could perform this operation without
1355 contacting the server, although using @code{remove} may cause the server
1356 to perform a few more checks.
1357
1358 The client sends a subsequent @code{ci} request to actually record the
1359 removal in the repository.
1360
1361 @item edit \n
1362 Response expected: yes.  Actually do the @code{cvs edit} command.  This uses
1363 any previous @code{Argument}, @code{Directory}, @code{Entry}, @code{LocalDir},
1364 or @code{Hostname} requests, if they have been sent.  Unless the user has
1365 requested that edits not be granted unless no one else is editing a file, a
1366 local edit followed by an attempt to send @code{Notify} requests to the
1367 server is preferred.
1368
1369 @item watch-on \n
1370 @itemx watch-off \n
1371 @itemx watch-add \n
1372 @itemx watch-remove \n
1373 Response expected: yes.  Actually do the @code{cvs watch on}, @code{cvs
1374 watch off}, @code{cvs watch add}, and @code{cvs watch remove} commands,
1375 respectively.  This uses any previous @code{Argument},
1376 @code{Directory}, @code{Entry}, or @code{Modified}
1377 requests, if they have been sent.  The last @code{Directory} sent
1378 specifies the working directory at the time of the operation.
1379
1380 @item release \n
1381 Response expected: yes.  Note that a @code{cvs release} command has
1382 taken place and update the history file accordingly.
1383
1384 @item global-list-quiet \n
1385 Response expected: yes.  This request is a synonym for noop, but its existance
1386 notifies the client that a @code{-q} option to @code{list} and @code{rlist}
1387 will be rejected.  This, in a reverse-logic sort of way, is here so that when
1388 it @emph{isn't} received, as for instance from CVSNT, the client will know that
1389 the quiet option has to be sent as a command option rather than a global
1390 option.
1391
1392 @item noop \n
1393 Response expected: yes.  This request is a null command in the sense
1394 that it doesn't do anything, but merely (as with any other requests
1395 expecting a response) sends back any responses pertaining to pending
1396 errors, pending @code{Notified} responses, etc.
1397 The @code{Root} request need not have been previously sent.
1398
1399 @item update-patches \n
1400 Response expected: yes.
1401 This request does not actually do anything.  It is used as a signal that
1402 the server is able to generate patches when given an @code{update}
1403 request.  The client must issue the @code{-u} argument to @code{update}
1404 in order to receive patches.
1405
1406 @item gzip-file-contents @var{level} \n
1407 Response expected: no.  Note that this request does not follow the
1408 response convention stated above.  @code{Gzip-stream} is suggested
1409 instead of @code{gzip-file-contents} as it gives better compression; the
1410 only reason to implement the latter is to provide compression with
1411 @sc{cvs} 1.8 and earlier.  The @code{gzip-file-contents} request asks
1412 the server to compress files it sends to the client using @code{gzip}
1413 (RFC1952/1951) compression, using the specified level of compression.
1414 If this request is not made, the server must not compress files.
1415
1416 This is only a hint to the server.  It may still decide (for example, in
1417 the case of very small files, or files that already appear to be
1418 compressed) not to do the compression.  Compression is indicated by a
1419 @samp{z} preceding the file length.
1420
1421 Availability of this request in the server indicates to the client that
1422 it may compress files sent to the server, regardless of whether the
1423 client actually uses this request.
1424
1425 @item wrapper-sendme-rcsOptions \n
1426 Response expected: yes.
1427 Request that the server transmit mappings from filenames to keyword
1428 expansion modes in @code{Wrapper-rcsOption} responses.
1429
1430 @item version \n
1431 Response expected: yes.
1432 Request that the server transmit its version message.
1433 The @code{Root} request need not have been previously sent.
1434
1435 @item @var{other-request} @var{text} \n
1436 Response expected: yes.
1437 Any unrecognised request expects a response, and does not
1438 contain any additional data.  The response will normally be something like
1439 @samp{error  unrecognized request}, but it could be a different error if
1440 a previous request which doesn't expect a response produced an error.
1441 @end table
1442
1443 When the client is done, it drops the connection.
1444
1445 @node Response intro
1446 @section Introduction to Responses
1447
1448 After a command which expects a response, the server sends however many
1449 of the following responses are appropriate.  The server should not send
1450 data at other times (the current implementation may violate this
1451 principle in a few minor places, where the server is printing an error
1452 message and exiting---this should be investigated further).
1453
1454 Any set of responses always ends with @samp{error} or @samp{ok}.  This
1455 indicates that the response is over.
1456
1457 @c "file updating response" and "file update modifying response" are
1458 @c lame terms (mostly because they are so awkward).  Any better ideas?
1459 The responses @code{Checked-in}, @code{New-entry}, @code{Updated},
1460 @code{Created}, @code{Update-existing}, @code{Merged}, and
1461 @code{Patched} are refered to as @dfn{file updating} responses, because
1462 they change the status of a file in the working directory in some way.
1463 The responses @code{Mode}, @code{Mod-time}, and @code{Checksum} are
1464 referred to as @dfn{file update modifying} responses because they modify
1465 the next file updating response.  In no case shall a file update
1466 modifying response apply to a file updating response other than the next
1467 one.  Nor can the same file update modifying response occur twice for
1468 a given file updating response (if servers diagnose this problem, it may
1469 aid in detecting the case where clients send an update modifying
1470 response without following it by a file updating response).
1471
1472 @node Response pathnames
1473 @section The "pathname" in responses
1474
1475 Many of the responses contain something called @var{pathname}.
1476 @c FIXME: should better document when the specified repository needs to
1477 @c end in "/.".
1478 The name is somewhat misleading; it actually indicates a pair of
1479 pathnames.  First, a local directory name
1480 relative to the directory in which the command was given (i.e. the last
1481 @code{Directory} before the command).  Then a linefeed and a repository
1482 name.  Then a slash and the filename (without a @samp{,v} ending).
1483
1484 The repository name may be absolute or relative to the @var{pathname}
1485 sent with the @code{Root} request.  If absolute, the repository name must begin
1486 with the @var{pathname} sent with the @code{Root} request.  Relative or
1487 absolute, the repository name must specify a path underneath the @code{Root}
1488 @var{pathname}.
1489
1490 For example, for a file @file{i386.mh}
1491 which is in the local directory @file{gas.clean/config} and for which
1492 the repository name is @file{devo/gas/config}:
1493
1494 @example
1495 gas.clean/config/
1496 devo/gas/config/i386.mh
1497 @end example
1498
1499 If the server wants to tell the client to create a directory, then it
1500 merely uses the directory in any response, as described above, and the
1501 client should create the directory if it does not exist.  Note that this
1502 should only be done one directory at a time, in order to permit the
1503 client to correctly store the repository for each directory.  Servers
1504 can use requests such as @code{Clear-sticky},
1505 @code{Clear-static-directory}, or any other requests, to create
1506 directories.
1507 @c FIXME: Need example here of how "repository" needs to be sent for
1508 @c each directory, and cannot be correctly deduced from, say, the most
1509 @c deeply nested directory.
1510
1511 Some server
1512 implementations may poorly distinguish between a directory which should
1513 not exist and a directory which contains no files; in order to refrain
1514 from creating empty directories a client should both send the @samp{-P}
1515 option to @code{update} or @code{co}, and should also detect the case in
1516 which the server asks to create a directory but not any files within it
1517 (in that case the client should remove the directory or refrain from
1518 creating it in the first place).  Note that servers could clean this up
1519 greatly by only telling the client to create directories if the
1520 directory in question should exist, but until servers do this, clients
1521 will need to offer the @samp{-P} behavior described above.
1522
1523 @node Responses
1524 @section Responses
1525
1526 Here are the responses:
1527
1528 @table @code
1529 @item Valid-requests @var{request-list} \n
1530 Indicate what requests the server will accept.  @var{request-list}
1531 is a space separated list of tokens.  If the server supports sending
1532 patches, it will include @samp{update-patches} in this list.  The
1533 @samp{update-patches} request does not actually do anything.
1534
1535 @item Force-gzip \n
1536 Response expected: no.
1537 Indicates that the server requires compression.  The client must send a
1538 @code{Gzip-stream} request, though the requested @var{level} may be @samp{0}.
1539
1540 @item Referrer @var{CVSROOT}
1541 Request that the client store @var{CVSROOT} as the name of this server and that
1542 this name be passed via a @code{Referrer} @emph{request} to any subsequent
1543 servers contacted as a result of a @code{Redirect} response.  This can be
1544 useful to allow the secondary administrator to configure the @code{CVSROOT} the
1545 primary should use to update the secondary in case the client uses a
1546 non-standard name or even a name that is unique to the client for some reason.
1547
1548 @item Redirect @var{CVSROOT}
1549 Request that the client redirect its connection to @var{CVSROOT} and begin
1550 again.  This response is only valid in response to a @code{Command-prep}
1551 request.  If a client receives this response, it is expected to notify the
1552 write server it subsequently contacts of the CVSROOT of the server which
1553 redirected it using the @samp{Referrer} request.  This information makes it
1554 possible for primary servers to update the client's mirror first, hopefully
1555 minimizing race conditions on subsequent updates from the same client.
1556
1557 @item Checked-in @var{pathname} \n
1558 Additional data: New Entries line, \n.  This means a file @var{pathname}
1559 has been successfully operated on (checked in, added, etc.).  name in
1560 the Entries line is the same as the last component of @var{pathname}.
1561
1562 @item New-entry @var{pathname} \n
1563 Additional data: New Entries line, \n.  Like @code{Checked-in}, but the
1564 file is not up to date.
1565
1566 @item Updated @var{pathname} \n
1567 Additional data: New Entries line, \n, mode, \n, file transmission.  A
1568 new copy of the file is enclosed.  This is used for a new revision of an
1569 existing file, or for a new file, or for any other case in which the
1570 local (client-side) copy of the file needs to be updated, and after
1571 being updated it will be up to date.  If any directory in pathname does
1572 not exist, create it.  This response is not used if @code{Created} and
1573 @code{Update-existing} are supported.
1574
1575 @item Created @var{pathname} \n
1576 This is just like @code{Updated} and takes the same additional data, but
1577 is used only if no @code{Entry}, @code{Modified}, or
1578 @code{Unchanged} request has been sent for the file in question.  The
1579 distinction between @code{Created} and @code{Update-existing} is so
1580 that the client can give an error message in several cases: (1) there is
1581 a file in the working directory, but not one for which @code{Entry},
1582 @code{Modified}, or @code{Unchanged} was sent (for example, a file which
1583 was ignored, or a file for which @code{Questionable} was sent), (2)
1584 there is a file in the working directory whose name differs from the one
1585 mentioned in @code{Created} in ways that the client is unable to use to
1586 distinguish files.  For example, the client is case-insensitive and the
1587 names differ only in case.
1588
1589 @item Update-existing @var{pathname} \n
1590 This is just like @code{Updated} and takes the same additional data, but
1591 is used only if a @code{Entry}, @code{Modified}, or @code{Unchanged}
1592 request has been sent for the file in question.
1593
1594 This response, or @code{Merged}, indicates that the server has
1595 determined that it is OK to overwrite the previous contents of the file
1596 specified by @var{pathname}.  Provided that the client has correctly
1597 sent @code{Modified} or @code{Is-modified} requests for a modified file,
1598 and the file was not modified while CVS was running, the server can
1599 ensure that a user's modifications are not lost.
1600
1601 @item Merged @var{pathname} \n
1602 This is just like @code{Updated} and takes the same additional data,
1603 with the one difference that after the new copy of the file is enclosed,
1604 it will still not be up to date.  Used for the results of a merge, with
1605 or without conflicts.
1606
1607 It is useful to preserve an copy of what the file looked like before the
1608 merge.  This is basically handled by the server; before sending
1609 @code{Merged} it will send a @code{Copy-file} response.  For example, if
1610 the file is @file{aa} and it derives from revision 1.3, the
1611 @code{Copy-file} response will tell the client to copy @file{aa} to
1612 @file{.#aa.1.3}.  It is up to the client to decide how long to keep this
1613 file around; traditionally clients have left it around forever, thus
1614 letting the user clean it up as desired.  But another answer, such as
1615 until the next commit, might be preferable.
1616
1617 @item Rcs-diff @var{pathname} \n
1618 This is just like @code{Updated} and takes the same additional data,
1619 with the one difference that instead of sending a new copy of the file,
1620 the server sends an RCS change text.  This change text is produced by
1621 @samp{diff -n} (the GNU diff @samp{-a} option may also be used).  The
1622 client must apply this change text to the existing file.  This will only
1623 be used when the client has an exact copy of an earlier revision of a
1624 file.  This response is only used if the @code{update} command is given
1625 the @samp{-u} argument.
1626
1627 @item Patched @var{pathname} \n
1628 This is just like @code{Rcs-diff} and takes the same additional data,
1629 except that it sends a standard patch rather than an RCS change text.
1630 The patch is produced by @samp{diff -c} for @sc{cvs} 1.6 and later (see
1631 POSIX.2 for a description of this format), or @samp{diff -u} for
1632 previous versions of @sc{cvs}; clients are encouraged to accept either
1633 format.  Like @code{Rcs-diff}, this response is only used if the
1634 @code{update} command is given the @samp{-u} argument.
1635
1636 The @code{Patched} response is deprecated in favor of the
1637 @code{Rcs-diff} response.  However, older clients (CVS 1.9 and earlier)
1638 only support @code{Patched}.
1639
1640 @item Edit-file @var{pathname} \n
1641 Do the client-side portion of editing a file.
1642
1643 @item Mode @var{mode} \n
1644 This @var{mode} applies to the next file mentioned in
1645 @code{Checked-in}.  @code{Mode} is a file update modifying response
1646 as described in @ref{Response intro}.
1647
1648 @item Mod-time @var{time} \n
1649 Set the modification time of the next file sent to @var{time}.
1650 @code{Mod-time} is a file update modifying response
1651 as described in @ref{Response intro}.
1652 The
1653 @var{time} is in the format specified by RFC822 as modified by RFC1123.
1654 The server may specify any timezone it chooses; clients will want to
1655 convert that to their own timezone as appropriate.  An example of this
1656 format is:
1657
1658 @example
1659 26 May 1997 13:01:40 -0400
1660 @end example
1661
1662 There is no requirement that the client and server clocks be
1663 synchronised.  The server just sends its recommendation for a timestamp
1664 (based on its own clock, presumably), and the client should just believe
1665 it (this means that the time might be in the future, for example).
1666
1667 If the server does not send @code{Mod-time} for a given file, the client
1668 should pick a modification time in the usual way (usually, just let the
1669 operating system set the modification time to the time that the CVS
1670 command is running).
1671
1672 @item Checksum @var{checksum}\n
1673 The @var{checksum} applies to the next file sent (that is,
1674 @code{Checksum} is a file update modifying response
1675 as described in @ref{Response intro}).
1676 In the case of
1677 @code{Patched}, the checksum applies to the file after being patched,
1678 not to the patch itself.  The client should compute the checksum itself,
1679 after receiving the file or patch, and signal an error if the checksums
1680 do not match.  The checksum is the 128 bit MD5 checksum represented as
1681 32 hex digits (MD5 is described in RFC1321).
1682 This response is optional, and is only used if the
1683 client supports it (as judged by the @code{Valid-responses} request).
1684
1685 @item Copy-file @var{pathname} \n
1686 Additional data: @var{newname} \n.  Copy file @var{pathname} to
1687 @var{newname} in the same directory where it already is.  This does not
1688 affect @code{CVS/Entries}.
1689
1690 This can optionally be implemented as a rename instead of a copy.  The
1691 only use for it which currently has been identified is prior to a
1692 @code{Merged} response as described under @code{Merged}.  Clients can
1693 probably assume that is how it is being used, if they want to worry
1694 about things like how long to keep the @var{newname} file around.
1695
1696 @item Removed @var{pathname} \n
1697 The file has been removed from the repository (this is the case where
1698 cvs prints @samp{file foobar.c is no longer pertinent}).
1699
1700 @item Remove-entry @var{pathname} \n
1701 The file needs its entry removed from @code{CVS/Entries}, but the file
1702 itself is already gone (this happens in response to a @code{ci} request
1703 which involves committing the removal of a file).
1704
1705 @item Set-static-directory @var{pathname} \n
1706 This instructs the client to set the @code{Entries.Static} flag, which
1707 it should then send back to the server in a @code{Static-directory}
1708 request whenever the directory is operated on.  @var{pathname} ends in a
1709 slash; its purpose is to specify a directory, not a file within a
1710 directory.
1711
1712 @item Clear-static-directory @var{pathname} \n
1713 Like @code{Set-static-directory}, but clear, not set, the flag.
1714
1715 @item Set-sticky @var{pathname} \n
1716 Additional data: @var{tagspec} \n.  Tell the client to set a sticky tag
1717 or date, which should be supplied with the @code{Sticky} request for
1718 future operations.  @var{pathname} ends in a slash; its purpose is to
1719 specify a directory, not a file within a directory.  The client should
1720 store @var{tagspec} and pass it back to the server as-is, to allow for
1721 future expansion.  The first character of @var{tagspec} is @samp{T} for
1722 a tag, @samp{D} for a date, or something else for future expansion.  The
1723 remainder of @var{tagspec} contains the actual tag or date.
1724
1725 @item Clear-sticky @var{pathname} \n
1726 Clear any sticky tag or date set by @code{Set-sticky}.
1727
1728 @item Template @var{pathname} \n
1729 Additional data: file transmission (note: compressed file transmissions
1730 are not supported).  @var{pathname} ends in a slash; its purpose is to
1731 specify a directory, not a file within a directory.  Tell the client to
1732 store the file transmission as the template log message, and then use
1733 that template in the future when prompting the user for a log message.
1734
1735 @item Set-checkin-prog @var{dir} \n
1736 Additional data: @var{prog} \n.  Tell the client to set a checkin
1737 program, which should be supplied with the @code{Checkin-prog} request
1738 for future operations.
1739
1740 @item Set-update-prog @var{dir} \n
1741 Additional data: @var{prog} \n.  Tell the client to set an update
1742 program, which should be supplied with the @code{Update-prog} request
1743 for future operations.
1744
1745 @item Notified @var{pathname} \n
1746 Indicate to the client that the notification for @var{pathname} has been
1747 done.  There should be one such response for every @code{Notify}
1748 request; if there are several @code{Notify} requests for a single file,
1749 the requests should be processed in order; the first @code{Notified}
1750 response pertains to the first @code{Notify} request, etc.
1751
1752 @item Module-expansion @var{pathname} \n
1753 Return a file or directory
1754 which is included in a particular module.  @var{pathname} is relative
1755 to cvsroot, unlike most pathnames in responses.  @var{pathname} should
1756 be used to look and see whether some or all of the module exists on
1757 the client side; it is not necessarily suitable for passing as an
1758 argument to a @code{co} request (for example, if the modules file
1759 contains the @samp{-d} option, it will be the directory specified with
1760 @samp{-d}, not the name of the module).
1761
1762 @item Wrapper-rcsOption @var{pattern} -k '@var{option}' \n
1763 Transmit to the client a filename pattern which implies a certain
1764 keyword expansion mode.  The @var{pattern} is a wildcard pattern (for
1765 example, @samp{*.exe}.  The @var{option} is @samp{b} for binary, and so
1766 on.  Note that although the syntax happens to resemble the syntax in
1767 certain CVS configuration files, it is more constrained; there must be
1768 exactly one space between @var{pattern} and @samp{-k} and exactly one
1769 space between @samp{-k} and @samp{'}, and no string is permitted in
1770 place of @samp{-k} (extensions should be done with new responses, not by
1771 extending this one, for graceful handling of @code{Valid-responses}).
1772
1773 @item M @var{text} \n
1774 A one-line message for the user.
1775 Note that the format of @var{text} is not designed for machine parsing.
1776 Although sometimes scripts and clients will have little choice, the
1777 exact text which is output is subject to vary at the discretion of the
1778 server and the example output given in this document is just that,
1779 example output.  Servers are encouraged to use the @samp{MT} response,
1780 and future versions of this document will hopefully standardise more of
1781 the @samp{MT} tags; see @ref{Text tags}.
1782
1783 @item LOGM @var{text} \n
1784 Exactly the same as @code{M} but only sent if the client indicates
1785 supporting it via @code{Valid-responses}, used exclusively for log
1786 message payload (that is, in @code{cvs log} and @code{cvs rlog},
1787 the text body the user originally has entered with the @samp{-m}
1788 option to the @code{ci} request).
1789
1790 @item Mbinary \n
1791 Additional data: file transmission (note: compressed file transmissions
1792 are not supported).  This is like @code{M}, except the contents of the
1793 file transmission are binary and should be copied to standard output
1794 without translation to local text file conventions.  To transmit a text
1795 file to standard output, servers should use a series of @code{M} requests.
1796
1797 @item E @var{text} \n
1798 Same as @code{M} but send to stderr not stdout.
1799
1800 @item F \n
1801 @c FIXME: The second sentence, defining "flush", is somewhat off the top
1802 @c of my head.  Is there some text we can steal from ANSI C or someplace
1803 @c which is more carefully thought out?
1804 Flush stderr.  That is, make it possible for the user to see what has
1805 been written to stderr (it is up to the implementation to decide exactly
1806 how far it should go to ensure this).
1807
1808 @item MT @var{tagname} @var{data} \n
1809
1810 This response provides for tagged text.  It is similar to
1811 SGML/HTML/XML in that the data is structured and a naive application
1812 can also make some sense of it without understanding the structure.
1813 The syntax is not SGML-like, however, in order to fit into the CVS
1814 protocol better and (more importantly) to make it easier to parse,
1815 especially in a language like perl or awk.
1816
1817 The @var{tagname} can have several forms.  If it starts with @samp{a}
1818 to @samp{z} or @samp{A} to @samp{Z}, then it represents tagged text.
1819 If the implementation recognises @var{tagname}, then it may interpret
1820 @var{data} in some particular fashion.  If the implementation does not
1821 recognise @var{tagname}, then it should simply treat @var{data} as
1822 text to be sent to the user (similar to an @code{M} response).  There
1823 are two tags which are general purpose.  The @samp{text} tag is
1824 similar to an unrecognised tag in that it provides text which will
1825 ordinarily be sent to the user.  The @samp{newline} tag is used
1826 without @var{data} and indicates that a newline will ordinarily be
1827 sent to the user (there is no provision for embedding newlines in the
1828 @var{data} of other tagged text responses).
1829
1830 If @var{tagname} starts with @samp{+} it indicates a start tag and if
1831 it starts with @samp{-} it indicates an end tag.  The remainder of
1832 @var{tagname} should be the same for matching start and end tags, and
1833 tags should be nested (for example one could have tags in the
1834 following order @code{+bold} @code{+italic} @code{text} @code{-italic}
1835 @code{-bold} but not @code{+bold} @code{+italic} @code{text}
1836 @code{-bold} @code{-italic}).  A particular start and end tag may be
1837 documented to constrain the tagged text responses which are valid
1838 between them.
1839
1840 Note that if @var{data} is present there will always be exactly one
1841 space between @var{tagname} and @var{data}; if there is more than one
1842 space, then the spaces beyond the first are part of @var{data}.
1843
1844 Here is an example of some tagged text responses.  Note that there is
1845 a trailing space after @samp{Checking in} and @samp{initial revision:}
1846 and there are two trailing spaces after @samp{<--}.  Such trailing
1847 spaces are, of course, part of @var{data}.
1848
1849 @example
1850 MT +checking-in
1851 MT text Checking in 
1852 MT fname gz.tst
1853 MT text ;
1854 MT newline
1855 MT rcsfile /home/kingdon/zwork/cvsroot/foo/gz.tst,v
1856 MT text   <--  
1857 MT fname gz.tst
1858 MT newline
1859 MT text initial revision: 
1860 MT init-rev 1.1
1861 MT newline
1862 MT text done
1863 MT newline
1864 MT -checking-in
1865 @end example
1866
1867 If the client does not support the @samp{MT} response, the same
1868 responses might be sent as:
1869
1870 @example
1871 M Checking in gz.tst;
1872 M /home/kingdon/zwork/cvsroot/foo/gz.tst,v  <--  gz.tst
1873 M initial revision: 1.1
1874 M done
1875 @end example
1876
1877 For a list of specific tags, see @ref{Text tags}.
1878
1879 @item error @var{errno-code} @samp{ } @var{text} \n
1880 The command completed with an error.  @var{errno-code} is a symbolic
1881 error code (e.g. @code{ENOENT}); if the server doesn't support this
1882 feature, or if it's not appropriate for this particular message, it just
1883 omits the errno-code (in that case there are two spaces after
1884 @samp{error}).  Text is an error message such as that provided by
1885 strerror(), or any other message the server wants to use.
1886 The @var{text} is like the @code{M} response, in the sense that it is
1887 not particularly intended to be machine-parsed; servers may wish to
1888 print an error message with @code{MT} responses, and then issue a
1889 @code{error} response without @var{text} (although it should be noted
1890 that @code{MT} currently has no way of flagging the output as intended
1891 for standard error, the way that the @code{E} response does).
1892
1893 @item ok \n
1894 The command completed successfully.
1895 @end table
1896
1897 @node Text tags
1898 @section Tags for the MT tagged text response
1899
1900 The @code{MT} response, as described in @ref{Responses}, offers a
1901 way for the server to send tagged text to the client.  This section
1902 describes specific tags.  The intention is to update this section as
1903 servers add new tags.
1904
1905 In the following descriptions, @code{text} and @code{newline} tags are
1906 omitted.  Such tags contain information which is intended for users (or
1907 to be discarded), and are subject to change at the whim of the server.
1908 To avoid being vulnerable to such whim, clients should look for the tags
1909 listed here, not @code{text}, @code{newline}, or other tags.
1910
1911 The following tag means to indicate to the user that a file has been
1912 updated.  It is more or less redundant with the @code{Created} and
1913 @code{Update-existing} responses, but we don't try to specify here
1914 whether it occurs in exactly the same circumstances as @code{Created}
1915 and @code{Update-existing}.  The @var{name} is the pathname of the file
1916 being updated relative to the directory in which the command is
1917 occurring (that is, the last @code{Directory} request which is sent
1918 before the command).
1919
1920 @example
1921 MT +updated
1922 MT fname @var{name}
1923 MT -updated
1924 @end example
1925
1926 The @code{importmergecmd} tag is used when doing an import which has
1927 conflicts, or when doing an import with the @samp{-X} flag.
1928 The client can use it to report how to merge in the newly
1929 imported changes.  The @var{count} is the number of conflicts, or the
1930 string @code{No} if no conflicts occurred.  (The latter will only be
1931 sent for imports run with the @samp{-X} flag.)  The
1932 newly imported changes can be merged by running the following command:
1933 @smallexample
1934 cvs checkout -j @var{tag1} -j @var{tag2} @var{repository}
1935 @end smallexample
1936
1937 @example
1938 MT +importmergecmd
1939 MT conflicts @var{count}
1940 MT mergetag1 @var{tag1}
1941 MT mergetag2 @var{tag2}
1942 MT repository @var{repository}
1943 MT -importmergecmd
1944 @end example
1945
1946 @node Example
1947 @section Example
1948
1949 @c The C:/S: convention is in imitation of RFC1869 (and presumably
1950 @c other RFC's).  In other formatting concerns, we might want to think
1951 @c about whether there is an easy way to provide RFC1543 formatting
1952 @c (without negating the advantages of texinfo), and whether we should
1953 @c use RFC2234 BNF (I fear that would be less clear than
1954 @c what we do now, however).  Plus what about RFC2119 terminology (MUST,
1955 @c SHOULD, &c) or ISO terminology (shall, should, or whatever they are)?
1956 Here is an example; lines are prefixed by @samp{C: } to indicate the
1957 client sends them or @samp{S: } to indicate the server sends them.
1958
1959 The client starts by connecting, sending the root, and completing the
1960 protocol negotiation.  In actual practice the lists of valid responses
1961 and requests would be longer.
1962 @c The reason that we artificially shorten the lists is to avoid phony
1963 @c line breaks.  Any better solutions?
1964 @c Other than that, this exchange is taken verbatim from the data
1965 @c exchanged by CVS (as of Nov 1996).  That is why some of the requests and
1966 @c reponses are not quite what you would pick for pedagogical purposes.
1967
1968 @example
1969 C: Root /u/cvsroot
1970 C: Valid-responses ok error Checked-in M E
1971 C: valid-requests
1972 S: Valid-requests Root Directory Entry Modified Argument Argumentx ci co
1973 S: ok
1974 C: UseUnchanged
1975 @end example
1976
1977 The client wants to check out the @code{supermunger} module into a fresh
1978 working directory.  Therefore it first expands the @code{supermunger}
1979 module; this step would be omitted if the client was operating on a
1980 directory rather than a module.
1981 @c Why does it send Directory here?  The description of expand-modules
1982 @c doesn't really say much of anything about what use, if any, it makes of
1983 @c Directory and similar requests sent previously.
1984
1985 @example
1986 C: Argument supermunger
1987 C: Directory .
1988 C: .
1989 C: expand-modules
1990 @end example
1991
1992 The server replies that the @code{supermunger} module expands to the
1993 directory @code{supermunger} (the simplest case):
1994
1995 @example
1996 S: Module-expansion supermunger
1997 S: ok
1998 @end example
1999
2000 The client then proceeds to check out the directory.  The fact that it
2001 sends only a single @code{Directory} request which specifies @samp{.}
2002 for the working directory means that there is not already a
2003 @code{supermunger} directory on the client.
2004 @c What is -N doing here?
2005
2006 @example
2007 C: Argument -N
2008 C: Argument supermunger
2009 C: Directory .
2010 C: .
2011 C: co
2012 @end example
2013
2014 The server replies with the requested files.  In this example, there is
2015 only one file, @file{mungeall.c}.  The @code{Clear-sticky} and
2016 @code{Clear-static-directory} requests are sent by the current
2017 implementation but they have no effect because the default is for those
2018 settings to be clear when a directory is newly created.
2019
2020 @example
2021 S: Clear-sticky supermunger/
2022 S: /u/cvsroot/supermunger/
2023 S: Clear-static-directory supermunger/
2024 S: /u/cvsroot/supermunger/
2025 S: E cvs server: Updating supermunger
2026 S: M U supermunger/mungeall.c
2027 S: Created supermunger/
2028 S: /u/cvsroot/supermunger/mungeall.c
2029 S: /mungeall.c/1.1///
2030 S: u=rw,g=r,o=r
2031 S: 26
2032 S: int mein () @{ abort (); @}
2033 S: ok
2034 @end example
2035
2036 The current client implementation would break the connection here and make a
2037 new connection for the next command.  However, the protocol allows it
2038 to keep the connection open and continue, which is what we show here.
2039
2040 After the user modifies the file and instructs the client to check it
2041 back in.  The client sends arguments to specify the log message and file
2042 to check in:
2043
2044 @example
2045 C: Argument -m
2046 C: Argument Well, you see, it took me hours and hours to find
2047 C: Argumentx this typo and I searched and searched and eventually
2048 C: Argumentx had to ask John for help.
2049 C: Argument mungeall.c
2050 @end example
2051
2052 It also sends information about the contents of the working directory,
2053 including the new contents of the modified file.  Note that the user has
2054 changed into the @file{supermunger} directory before executing this
2055 command; the top level directory is a user-visible concept because the
2056 server should print filenames in @code{M} and @code{E} responses
2057 relative to that directory.
2058 @c We are waving our hands about the order of the requests.  "Directory"
2059 @c and "Argument" can be in any order, but this probably isn't specified
2060 @c very well.
2061
2062 @example
2063 C: Directory .
2064 C: supermunger
2065 C: Entry /mungeall.c/1.1///
2066 C: Modified mungeall.c
2067 C: u=rw,g=r,o=r
2068 C: 26
2069 C: int main () @{ abort (); @}
2070 @end example
2071
2072 And finally, the client issues the checkin command (which makes use of
2073 the data just sent):
2074
2075 @example
2076 C: ci
2077 @end example
2078
2079 And the server tells the client that the checkin succeeded:
2080
2081 @example
2082 S: M Checking in mungeall.c;
2083 S: E /u/cvsroot/supermunger/mungeall.c,v  <--  mungeall.c
2084 S: E new revision: 1.2; previous revision: 1.1
2085 S: E done
2086 S: Mode u=rw,g=r,o=r
2087 S: Checked-in ./
2088 S: /u/cvsroot/supermunger/mungeall.c
2089 S: /mungeall.c/1.2///
2090 S: ok
2091 @end example
2092
2093 @node Requirements
2094 @section Required versus optional parts of the protocol
2095
2096 The following are part of every known implementation of the CVS protocol
2097 (except obsolete, pre-1.5, versions of CVS) and it is considered
2098 reasonable behavior to completely fail to work if you are connected with
2099 an implementation which attempts to not support them.  Requests:
2100 @code{Root}, @code{Valid-responses}, @code{valid-requests},
2101 @code{Directory}, @code{Entry}, @code{Modified}, @code{Unchanged},
2102 @code{Argument}, @code{Argumentx}, @code{ci}, @code{co}, @code{update}.
2103 Responses: @code{ok}, @code{error}, @code{Valid-requests},
2104 @code{Checked-in}, @code{Updated}, @code{Merged}, @code{Removed},
2105 @code{M}, @code{E}.
2106
2107 A server need not implement @code{Repository}, but in order to interoperate
2108 with CVS 1.5 through 1.9 it must claim to implement it (in
2109 @code{Valid-requests}).  The client will not actually send the request.
2110
2111 @node Obsolete
2112 @section Obsolete protocol elements
2113
2114 This section briefly describes protocol elements which are obsolete.
2115 There is no attempt to document them in full detail.
2116
2117 There was a @code{Repository} request which was like @code{Directory}
2118 except it only provided @var{repository}, and the local directory was
2119 assumed to be similarly named.
2120
2121 If the @code{UseUnchanged} request was not sent, there was a @code{Lost}
2122 request which was sent to indicate that a file did not exist in the
2123 working directory, and the meaning of sending @code{Entries} without
2124 @code{Lost} or @code{Modified} was different.  All current clients (CVS
2125 1.5 and later) will send @code{UseUnchanged} if it is supported.
2126
2127 @node Protocol Notes
2128 @chapter Notes on the Protocol
2129
2130 A number of enhancements are possible.  Also see the file @sc{todo} in
2131 the @sc{cvs} source distribution, which has further ideas concerning
2132 various aspects of @sc{cvs}, some of which impact the protocol.
2133 Similarly, the @url{http://www.nongnu.org/cvs/} site, in particular the
2134 @cite{Development} pages.
2135
2136 @itemize @bullet
2137 @item
2138 The @code{Modified} request could be speeded up by sending diffs rather
2139 than entire files.  The client would need some way to keep the version
2140 of the file which was originally checked out; probably requiring the use
2141 of "cvs edit" in this case is the most sensible course (the "cvs edit"
2142 could be handled by a package like VC for emacs).  This would also allow
2143 local operation of @code{cvs diff} without arguments.
2144
2145 @item
2146 The fact that @code{pserver} requires an extra network turnaround in
2147 order to perform authentication would be nice to avoid.  This relates to
2148 the issue of reporting errors; probably the clean solution is to defer
2149 the error until the client has issued a request which expects a
2150 response.  To some extent this might relate to the next item (in terms
2151 of how easy it is to skip a whole bunch of requests until we get to one
2152 that expects a response).  I know that the kerberos code doesn't wait in
2153 this fashion, but that probably can cause network deadlocks and perhaps
2154 future problems running over a transport which is more transaction
2155 oriented than TCP.  On the other hand I'm not sure it is wise to make
2156 the client conduct a lengthy upload only to find there is an
2157 authentication failure.
2158
2159 @item
2160 The protocol uses an extra network turnaround for protocol negotiation
2161 (@code{valid-requests}).  It might be nice to avoid this by having the
2162 client be able to send requests and tell the server to ignore them if
2163 they are unrecognised (different requests could produce a fatal error if
2164 unrecognised).  To do this there should be a standard syntax for
2165 requests.  For example, perhaps all future requests should be a single
2166 line, with mechanisms analogous to @code{Argumentx}, or several requests
2167 working together, to provide greater amounts of information.  Or there
2168 might be a standard mechanism for counted data (analogous to that used
2169 by @code{Modified}) or continuation lines (like a generalised
2170 @code{Argumentx}).  It would be useful to compare what HTTP is planning
2171 in this area; last I looked they were contemplating something called
2172 Protocol Extension Protocol but I haven't looked at the relevant IETF
2173 documents in any detail.  Obviously, we want something as simple as
2174 possible (but no simpler).
2175
2176 @item
2177 The scrambling algorithm in the CVS client and server actually support
2178 more characters than those documented in @ref{Password scrambling}.
2179 Someday we are going to either have to document them all (but this is
2180 not as easy as it may look, see below), or (gradually and with adequate
2181 process) phase out the support for other characters in the CVS
2182 implementation.  This business of having the feature partly undocumented
2183 isn't a desirable state long-term.
2184
2185 The problem with documenting other characters is that unless we know
2186 what character set is in use, there is no way to make a password
2187 portable from one system to another.  For example, a with a circle on
2188 top might have different encodings in different character sets.
2189
2190 It @emph{almost} works to say that the client picks an arbitrary,
2191 unknown character set (indeed, having the CVS client know what character
2192 set the user has in mind is a hard problem otherwise), and scrambles
2193 according to a certain octet<->octet mapping.  There are two problems
2194 with this.  One is that the protocol has no way to transmit character 10
2195 decimal (linefeed), and the current server and clients have no way to
2196 handle 0 decimal (NUL).  This may cause problems with certain multibyte
2197 character sets, in which octets 10 and 0 will appear in the middle of
2198 other characters.  The other problem, which is more minor and possibly
2199 not worth worrying about, is that someone can type a password on one
2200 system and then go to another system which uses a different encoding for
2201 the same characters, and have their password not work.
2202
2203 The restriction to the ISO646 invariant subset is the best approach for
2204 strings which are not particularly significant to users.  Passwords are
2205 visible enough that this is somewhat doubtful as applied here.  ISO646
2206 does, however, have the virtue (!?) of offending everyone.  It is easy
2207 to say "But the $ is right on people's keyboards!  Surely we can't
2208 forbid that".  From a human factors point of view, that makes quite a
2209 bit of sense.  The contrary argument, of course, is that a with a circle
2210 on top, or some of the characters poorly handled by Unicode, are on
2211 @emph{someone}'s keyboard.
2212
2213 @end itemize
2214
2215 @bye