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