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